feat: Add tool call history tracking for MCP operations

- Implement ToolHistoryTracker for session-based tracking - Add @track_tool_call decorator for non-intrusive tracking - Create tool_history, get_tool_call, and clear_tool_history MCP tools - Apply tracking to write_note, read_note, and search_notes as examples - Add comprehensive unit tests for history functionality - Zero performance impact on existing tools Fixes #265 Co-authored-by: Paul Hernandez <phernandez@users.noreply.github.com>
2026-06-21 13:47:35 +00:00 · 2025-09-26 14:52:15 +00:00
218 changed files with 9674 additions and 35051 deletions
@@ -15,16 +15,10 @@ Create a stable release using the automated justfile target with comprehensive v
 You are an expert release manager for the Basic Memory project. When the user runs `/release`, execute the following steps:

 ### Step 1: Pre-flight Validation
-
-#### Version Check
-1. Check current version in `src/basic_memory/__init__.py`
-2. Verify new version format matches `v\d+\.\d+\.\d+` pattern
-3. Confirm version is higher than current version
-
-#### Git Status
-1. Check current git status for uncommitted changes
-2. Verify we're on the `main` branch
-3. Confirm no existing tag with this version
+1. Verify version format matches `v\d+\.\d+\.\d+` pattern
+2. Check current git status for uncommitted changes  
+3. Verify we're on the `main` branch
+4. Confirm no existing tag with this version

 #### Documentation Validation
 1. **Changelog Check**
@@ -45,83 +39,19 @@ The justfile target handles:
 - ✅ Version update in `src/basic_memory/__init__.py`
 - ✅ Automatic commit with proper message
 - ✅ Tag creation and pushing to GitHub
- ✅ Release workflow trigger (automatic on tag push)
-
-The GitHub Actions workflow (`.github/workflows/release.yml`) then:
- ✅ Builds the package using `uv build`
- ✅ Creates GitHub release with auto-generated notes
- ✅ Publishes to PyPI
- ✅ Updates Homebrew formula (stable releases only)
+- ✅ Release workflow trigger

 ### Step 3: Monitor Release Process
-1. Verify tag push triggered the workflow (should start automatically within seconds)
-2. Monitor workflow progress at: https://github.com/basicmachines-co/basic-memory/actions
-3. Watch for successful completion of both jobs:
-   - `release` - Builds package and publishes to PyPI
-   - `homebrew` - Updates Homebrew formula (stable releases only)
-4. Check for any workflow failures and investigate logs if needed
+1. Check that GitHub Actions workflow starts successfully
+2. Monitor workflow completion at: https://github.com/basicmachines-co/basic-memory/actions
+3. Verify PyPI publication
+4. Test installation: `uv tool install basic-memory`

 ### Step 4: Post-Release Validation
-
-#### GitHub Release
-1. Verify GitHub release is created at: https://github.com/basicmachines-co/basic-memory/releases/tag/<version>
-2. Check that release notes are auto-generated from commits
-3. Validate release assets (`.whl` and `.tar.gz` files are attached)
-
-#### PyPI Publication
-1. Verify package published at: https://pypi.org/project/basic-memory/<version>/
-2. Test installation: `uv tool install basic-memory`
-3. Verify installed version: `basic-memory --version`
-
-#### Homebrew Formula (Stable Releases Only)
-1. Check formula update at: https://github.com/basicmachines-co/homebrew-basic-memory
-2. Verify formula version matches release
-3. Test Homebrew installation: `brew install basicmachines-co/basic-memory/basic-memory`
-
-#### Website Updates
-
-**1. basicmachines.co** (`/Users/drew/code/basicmachines.co`)
-   - **Goal**: Update version number displayed on the homepage
-   - **Location**: Search for "Basic Memory v0." in the codebase to find version displays
-   - **What to update**:
-     - Hero section heading that shows "Basic Memory v{VERSION}"
-     - "What's New in v{VERSION}" section heading
-     - Feature highlights array (look for array of features with title/description)
-   - **Process**:
-     1. Pull latest from GitHub: `git pull origin main`
-     2. Create release branch: `git checkout -b release/v{VERSION}`
-     3. Search codebase for current version number (e.g., "v0.16.1")
-     4. Update version numbers to new release version
-     5. Update feature highlights with 3-5 key features from this release (extract from CHANGELOG.md)
-     6. Commit changes: `git commit -m "chore: update to v{VERSION}"`
-     7. Push branch: `git push origin release/v{VERSION}`
-   - **Deploy**: Follow deployment process for basicmachines.co
-
-**2. docs.basicmemory.com** (`/Users/drew/code/docs.basicmemory.com`)
-   - **Goal**: Add new release notes section to the latest-releases page
-   - **File**: `src/pages/latest-releases.mdx`
-   - **What to do**:
-     1. Pull latest from GitHub: `git pull origin main`
-     2. Create release branch: `git checkout -b release/v{VERSION}`
-     3. Read the existing file to understand the format and structure
-     4. Read `/Users/drew/code/basic-memory/CHANGELOG.md` to get release content
-     5. Add new release section **at the top** (after MDX imports, before other releases)
-     6. Follow the existing pattern:
-        - Heading: `## [v{VERSION}](github-link) — YYYY-MM-DD`
-        - Focus statement if applicable
-        - `<Info>` block with highlights (3-5 key items)
-        - Sections for Features, Bug Fixes, Breaking Changes, etc.
-        - Link to full changelog at the end
-        - Separator `---` between releases
-     7. Commit changes: `git commit -m "docs: add v{VERSION} release notes"`
-     8. Push branch: `git push origin release/v{VERSION}`
-   - **Source content**: Extract and format sections from CHANGELOG.md for this version
-   - **Deploy**: Follow deployment process for docs.basicmemory.com
-
-**4. Announce Release**
-   - Post to Discord community if significant changes
-   - Update social media if major release
-   - Notify users via appropriate channels
+1. Verify GitHub release is created automatically
+2. Check PyPI publication
+3. Validate release assets
+4. Update any post-release documentation

 ## Pre-conditions Check
 Before starting, verify:
@@ -144,18 +74,13 @@ Before starting, verify:
 🏷️  Tag: v0.13.2
 📋 GitHub Release: https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.2
 📦 PyPI: https://pypi.org/project/basic-memory/0.13.2/
-🍺 Homebrew: https://github.com/basicmachines-co/homebrew-basic-memory
 🚀 GitHub Actions: Completed

-Install with pip/uv:
-  uv tool install basic-memory
-
-Install with Homebrew:
-  brew install basicmachines-co/basic-memory/basic-memory
+Install with:
+uv tool install basic-memory

 Users can now upgrade:
-  uv tool upgrade basic-memory
-  brew upgrade basic-memory
+uv tool upgrade basic-memory
 ```

 ## Context
@@ -164,6 +89,4 @@ Users can now upgrade:
 - Uses the automated justfile target for consistency
 - Version is automatically updated in `__init__.py`
 - Triggers automated GitHub release with changelog
- Package is published to PyPI for `pip` and `uv` users
- Homebrew formula is automatically updated for stable releases
- Supports multiple installation methods (uv, pip, Homebrew)
+- Leverages uv-dynamic-versioning for package version management
@@ -1,19 +1,17 @@
 ---
-allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__read_note, mcp__basic-memory__search_notes, mcp__basic-memory__edit_note
-argument-hint: [create|status|show|review] [spec-name]
+allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__read_note, mcp__basic-memory__search_notes, mcp__basic-memory__edit_note, Task
+argument-hint: [create|status|implement|review] [spec-name]
 description: Manage specifications in our development process
 ---

 ## Context

-Specifications are managed in the Basic Memory "specs" project. All specs live in a centralized location accessible across all repositories via MCP tools.
-
-See SPEC-1 and SPEC-2 in the "specs" project for the full specification-driven development process.
+You are managing specifications using our specification-driven development process defined in @docs/specs/SPEC-001.md.

 Available commands:
 - `create [name]` - Create new specification
 - `status` - Show all spec statuses
- `show [spec-name]` - Read a specific spec
+- `implement [spec-name]` - Hand spec to appropriate agent
 - `review [spec-name]` - Review implementation against spec

 ## Your task
@@ -21,19 +19,23 @@ Available commands:
 Execute the spec command: `/spec $ARGUMENTS`

 ### If command is "create":
-1. Get next SPEC number by searching existing specs in "specs" project
-2. Create new spec using template from SPEC-2
-3. Use mcp__basic-memory__write_note with project="specs"
+1. Get next SPEC number by searching existing specs
+2. Create new spec using template from @docs/specs/Slash\ Commands\ Reference.md
+3. Place in `/specs` folder with title "SPEC-XXX: [name]"
 4. Include standard sections: Why, What, How, How to Evaluate

 ### If command is "status":
-1. Use mcp__basic-memory__search_notes with project="specs"
-2. Display table with spec number, title, and progress
-3. Show completion status from checkboxes in content
+1. Search all notes in `/specs` folder
+2. Display table with spec number, title, and status
+3. Show any dependencies or assigned agents

-### If command is "show":
-1. Use mcp__basic-memory__read_note with project="specs"
-2. Display the full spec content
+### If command is "implement":
+1. Read the specified spec
+2. Determine appropriate agent based on content:
+   - Frontend/UI → vue-developer
+   - Architecture/system → system-architect  
+   - Backend/API → python-developer
+3. Launch Task tool with appropriate agent and spec context

 ### If command is "review":
 1. Read the specified spec and its "How to Evaluate" section
@@ -47,5 +49,7 @@ Execute the spec command: `/spec $ARGUMENTS`
   - **Architecture compliance** - Component isolation, state management patterns
   - **Documentation completeness** - Implementation matches specification
 3. Provide honest, accurate assessment - do not overstate completeness
-4. Document findings and update spec with review results using mcp__basic-memory__edit_note
+4. Document findings and update spec with review results
 5. If gaps found, clearly identify what still needs to be implemented/tested
+
+Use the agent definitions from @docs/specs/Agent\ Definitions.md for implementation handoffs.
@@ -1,28 +0,0 @@
-# Basic Memory Environment Variables Example
-# Copy this file to .env and customize as needed
-# Note: .env files are gitignored and should never be committed
-
-# ============================================================================
-# PostgreSQL Test Database Configuration
-# ============================================================================
-# These variables allow you to override the default test database credentials
-# Default values match docker-compose-postgres.yml for local development
-#
-# Only needed if you want to use different credentials or a remote test database
-# By default, tests use: postgresql://basic_memory_user:dev_password@localhost:5433/basic_memory_test
-
-# Full PostgreSQL test database URL (used by tests and migrations)
-# POSTGRES_TEST_URL=postgresql+asyncpg://basic_memory_user:dev_password@localhost:5433/basic_memory_test
-
-# Individual components (used by justfile postgres-reset command)
-# POSTGRES_USER=basic_memory_user
-# POSTGRES_TEST_DB=basic_memory_test
-
-# ============================================================================
-# Production Database Configuration
-# ============================================================================
-# For production use, set these in your deployment environment
-# DO NOT use the test credentials above in production!
-
-# BASIC_MEMORY_DATABASE_BACKEND=postgres  # or "sqlite"
-# BASIC_MEMORY_DATABASE_URL=postgresql+asyncpg://user:password@host:port/database
@@ -71,12 +71,9 @@ jobs:
            - [ ] Proper error handling and logging
            - [ ] Performance considerations addressed
            - [ ] No sensitive data in logs or commits
-            
-            ## Compatability
-            - [ ] File path comparisons must be windows compatible
-            - [ ] Avoid using emojis and unicode characters in console and log output

            Read the CLAUDE.md file for detailed project context. For each checklist item, verify if it's satisfied and comment on any that need attention. Use inline comments for specific code issues and post a summary with checklist results.

          # Allow broader tool access for thorough code review
          claude_args: '--allowed-tools "Bash(gh pr:*),Bash(gh issue:*),Bash(gh api:*),Bash(git log:*),Bash(git show:*),Read,Grep,Glob"'
+
@@ -13,13 +13,12 @@ on:
    branches: [ "main" ]

 jobs:
-  test-sqlite:
-    name: Test SQLite (${{ matrix.os }}, Python ${{ matrix.python-version }})
+  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
-        python-version: [ "3.12", "3.13" ]
+        python-version: [ "3.12" ]
    runs-on: ${{ matrix.os }}

    steps:
@@ -61,67 +60,15 @@ jobs:
        run: |
          just typecheck

+      - name: Run type checks
+        run: |
+          just typecheck
+
      - name: Run linting
        run: |
          just lint

-      - name: Run tests (SQLite)
+      - name: Run tests
        run: |
          uv pip install pytest pytest-cov
-          just test-sqlite
-
-  test-postgres:
-    name: Test Postgres (Python ${{ matrix.python-version }})
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: [ "3.12", "3.13" ]
-    runs-on: ubuntu-latest
-
-    # Postgres service (only available on Linux runners)
-    services:
-      postgres:
-        image: postgres:17
-        env:
-          POSTGRES_DB: basic_memory_test
-          POSTGRES_USER: basic_memory_user
-          POSTGRES_PASSWORD: dev_password
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-        ports:
-          - 5433:5432
-
-    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
-
-      - name: Install just
-        run: |
-          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
-
-      - name: Create virtual env
-        run: |
-          uv venv
-
-      - name: Install dependencies
-        run: |
-          uv pip install -e .[dev]
-
-      - name: Run tests (Postgres)
-        run: |
-          uv pip install pytest pytest-cov
-          just test-postgres
+          just test
@@ -1,688 +1,5 @@
 # CHANGELOG

-## v0.16.2 (2025-11-16)
-
-### Bug Fixes
-
- **#429**: Use platform-native path separators in config.json
-  ([`6517e98`](https://github.com/basicmachines-co/basic-memory/commit/6517e98))
-  - Fixes config.json path separator issues on Windows
-  - Uses os.path.join for platform-native path construction
-  - Ensures consistent path handling across platforms
-
- **#427**: Add rclone installation checks for Windows bisync commands
-  ([`1af0539`](https://github.com/basicmachines-co/basic-memory/commit/1af0539))
-  - Validates rclone installation before running bisync commands
-  - Provides clear error messages when rclone is not installed
-  - Improves user experience on Windows
-
- **#421**: Main project always recreated on project list command
-  ([`cad7019`](https://github.com/basicmachines-co/basic-memory/commit/cad7019))
-  - Fixes issue where main project was recreated unnecessarily
-  - Improves project list command reliability
-  - Reduces unnecessary file system operations
-
-## v0.16.1 (2025-11-11)
-
-### Bug Fixes
-
- **#422**: Handle Windows line endings in rclone bisync
-  ([`e9d0a94`](https://github.com/basicmachines-co/basic-memory/commit/e9d0a94))
-  - Added `--compare=modtime` flag to rclone bisync to ignore size differences from line ending conversions
-  - Fixes issue where LF→CRLF conversion on Windows was treated as file corruption
-  - Resolves "corrupted on transfer: sizes differ" errors during cloud sync on Windows
-  - Users will need to run `--resync` once after updating to establish new baseline
-
-## v0.16.0 (2025-11-10)
-
-### Features
-
- **#417**: Add run_in_background parameter to sync endpoint
-  ([`7ccec7e`](https://github.com/basicmachines-co/basic-memory/commit/7ccec7e))
-  - New `run_in_background` parameter for async sync operations
-  - Improved API flexibility for long-running sync tasks
-  - Comprehensive test coverage for background sync behavior
-
- **#405**: SPEC-20 Simplified Project-Scoped Rclone Sync
-  ([`0b3272a`](https://github.com/basicmachines-co/basic-memory/commit/0b3272a))
-  - Simplified and more reliable cloud synchronization
-  - Project-scoped rclone configuration
-  - Better error handling and status reporting
-
- **#384**: Streaming Foundation & Async I/O Consolidation (SPEC-19)
-  ([`e78345f`](https://github.com/basicmachines-co/basic-memory/commit/e78345f))
-  - Foundation for streaming support in future releases
-  - Consolidated async I/O patterns across codebase
-  - Improved performance and resource management
-
- **#364**: Add circuit breaker for file sync failures
-  ([`434cdf2`](https://github.com/basicmachines-co/basic-memory/commit/434cdf2))
-  - Prevents cascading failures during sync operations
-  - Automatic recovery from transient errors
-  - Better resilience in cloud sync scenarios
-
- **#362**: Add --verbose and --no-gitignore options to cloud upload
-  ([`7f9c1a9`](https://github.com/basicmachines-co/basic-memory/commit/7f9c1a9))
-  - Enhanced upload control with verbose logging
-  - Option to bypass gitignore filtering when needed
-  - Better debugging and troubleshooting capabilities
-
- **#391**: Add delete_notes parameter to remove project endpoint
-  ([`c9946ec`](https://github.com/basicmachines-co/basic-memory/commit/c9946ec))
-  - Option to delete notes when removing projects
-  - Safer project cleanup workflows
-  - Prevents accidental data loss
-
-### Bug Fixes
-
- **#420**: Skip archive files during cloud upload
-  ([`49b2adc`](https://github.com/basicmachines-co/basic-memory/commit/49b2adc))
-  - Prevents uploading of zip, tar, gz and other archive files
-  - Reduces storage usage and upload time
-  - Better file filtering during cloud operations
-
- **#419**: Rename write_note entity_type to note_type for clarity
-  ([`1646572`](https://github.com/basicmachines-co/basic-memory/commit/1646572))
-  - Clearer parameter naming in write_note tool
-  - Improved API consistency and documentation
-  - Better developer experience
-
- **#418**: Quote string values in YAML frontmatter to handle special characters
-  ([`f0d7398`](https://github.com/basicmachines-co/basic-memory/commit/f0d7398))
-  - Fixes YAML parsing errors with special characters
-  - More robust frontmatter handling
-  - Prevents data corruption in edge cases
-
- **#415**: Handle dict objects in write_resource endpoint
-  ([`4614fd0`](https://github.com/basicmachines-co/basic-memory/commit/4614fd0))
-  - Fixes errors when writing dictionary resources
-  - Better type handling in resource endpoints
-  - Improved API robustness
-
- **#414**: Replace Unicode arrows with ASCII for Windows compatibility
-  ([`fc01f6a`](https://github.com/basicmachines-co/basic-memory/commit/fc01f6a))
-  - Fixes display issues on Windows terminals
-  - Better cross-platform compatibility
-  - Improved CLI user experience on Windows
-
- **#411**: Windows CLI Unicode encoding errors
-  ([`0ba6f21`](https://github.com/basicmachines-co/basic-memory/commit/0ba6f21))
-  - Resolves Unicode encoding issues on Windows
-  - Better handling of international characters
-  - Improved Windows platform support
-
- **#410**: Various rclone fixes for cloud sync on Windows
-  ([`c9946ec`](https://github.com/basicmachines-co/basic-memory/commit/c9946ec))
-  - Fixes cloud sync reliability on Windows
-  - Better path handling for Windows filesystem
-  - Improved rclone integration on Windows
-
- **#402**: Normalize YAML frontmatter types to prevent AttributeError
-  ([`a7d7cc5`](https://github.com/basicmachines-co/basic-memory/commit/a7d7cc5))
-  - Fixes AttributeError when reading frontmatter
-  - More robust type normalization
-  - Better error handling in markdown parsing
-
- **#396**: Strip duplicate headers in edit_note replace_section
-  ([`021af74`](https://github.com/basicmachines-co/basic-memory/commit/021af74))
-  - Prevents duplicate headers when replacing sections
-  - Cleaner note editing behavior
-  - Better content consistency
-
- **#395**: Simplify search_notes schema by removing Optional wrappers
-  ([`d775f7b`](https://github.com/basicmachines-co/basic-memory/commit/d775f7b))
-  - Cleaner API schema definition
-  - Better type safety and validation
-  - Improved developer experience
-
- **#394**: Add explicit type annotations to MCP tool parameters
-  ([`581b7b1`](https://github.com/basicmachines-co/basic-memory/commit/581b7b1))
-  - Better type safety in MCP tools
-  - Improved IDE support and autocomplete
-  - Clearer tool documentation
-
- **#389**: Handle null, empty, and string 'None' title in markdown frontmatter
-  ([`bb8da31`](https://github.com/basicmachines-co/basic-memory/commit/bb8da31))
-  - Fixes errors with malformed frontmatter titles
-  - More robust title handling
-  - Better error recovery
-
- **#380**: Optimize sync memory usage to prevent OOM on large projects
-  ([`4fd6d0c`](https://github.com/basicmachines-co/basic-memory/commit/4fd6d0c))
-  - Prevents out-of-memory errors on large knowledge bases
-  - Better memory management during sync
-  - Improved scalability
-
- **#379**: Handle YAML parsing errors gracefully in update_frontmatter
-  ([`32236cd`](https://github.com/basicmachines-co/basic-memory/commit/32236cd))
-  - Better error handling for malformed YAML
-  - Graceful degradation instead of crashes
-  - Improved robustness
-
- **#377**: Preserve mtime on WebDAV upload
-  ([`e6c8e36`](https://github.com/basicmachines-co/basic-memory/commit/e6c8e36))
-  - Maintains file modification times during upload
-  - Better sync accuracy
-  - Prevents unnecessary re-syncing
-
- **#370**: Prevent deleted projects from being recreated by background sync
-  ([`449b62d`](https://github.com/basicmachines-co/basic-memory/commit/449b62d))
-  - Fixes race condition with project deletion
-  - Better lifecycle management
-  - Prevents unwanted project recreation
-
- **#369**: Use filesystem timestamps for entity sync instead of database operation time
-  ([`b7497d7`](https://github.com/basicmachines-co/basic-memory/commit/b7497d7))
-  - More accurate sync detection
-  - Better handling of external file modifications
-  - Improved sync reliability
-
- **#368**: Handle YAML parsing errors and missing entity_type in markdown files
-  ([`d1431bd`](https://github.com/basicmachines-co/basic-memory/commit/d1431bd))
-  - Better error handling for malformed markdown
-  - Graceful handling of missing metadata
-  - Improved robustness
-
- **#367**: Resolve UNIQUE constraint violation in entity upsert with observations
-  ([`171bef7`](https://github.com/basicmachines-co/basic-memory/commit/171bef7))
-  - Fixes database constraint errors during sync
-  - Better handling of duplicate observations
-  - Improved data integrity
-
- **#366**: Terminate sync immediately when project is deleted
-  ([`729a5a3`](https://github.com/basicmachines-co/basic-memory/commit/729a5a3))
-  - Faster project deletion
-  - Better resource cleanup
-  - Improved user experience
-
- **#357**: Make project creation endpoint idempotent
-  ([`53fb13b`](https://github.com/basicmachines-co/basic-memory/commit/53fb13b))
-  - Prevents errors when creating existing projects
-  - Better API reliability
-  - Improved cloud integration
-
- **#353**: Handle None text values in Claude conversations importer
-  ([`bd6c834`](https://github.com/basicmachines-co/basic-memory/commit/bd6c834))
-  - Fixes import errors with empty messages
-  - Better error handling in importers
-  - Improved data migration
-
-### Performance Improvements
-
- Force full database sync after project sync/bisync operations
-  ([`2ad0ee9`](https://github.com/basicmachines-co/basic-memory/commit/2ad0ee9))
-  - Ensures database consistency after cloud operations
-  - Better sync reliability
-  - Improved data integrity
-
-### Documentation
-
- Add free trial information to README
-  ([`a7d7cc5`](https://github.com/basicmachines-co/basic-memory/commit/a7d7cc5), [`8aaddb6`](https://github.com/basicmachines-co/basic-memory/commit/8aaddb6))
-  - Updated README with Basic Memory Cloud trial info
-  - Better onboarding experience
-  - Clearer pricing information
-
- Announce Basic Memory Cloud launch in README
-  ([`d756531`](https://github.com/basicmachines-co/basic-memory/commit/d756531))
-  - Official cloud service announcement
-  - Updated documentation for cloud features
-  - Improved product positioning
-
-### Migration Guide
-
-No manual migration required. Upgrade with:
-
-```bash
-# Update via uv
-uv tool upgrade basic-memory
-
-# Or install fresh
-uv tool install basic-memory
-```
-
-**What's New in v0.16.0:**
- Streaming foundation and consolidated async I/O (SPEC-19)
- Simplified project-scoped rclone sync (SPEC-20)
- Circuit breaker for sync failure resilience
- Enhanced Windows platform support
- Improved cloud upload with verbose and gitignore options
- Better error handling across YAML parsing and frontmatter
- Memory optimization for large projects
- Archive file filtering during upload
-
-**Breaking Changes:**
- `write_note` parameter renamed: `entity_type` → `note_type` for clarity
-
-### Installation
-
-```bash
-# Latest stable release
-uv tool install basic-memory
-
-# Update existing installation
-uv tool upgrade basic-memory
-
-# Docker
-docker pull ghcr.io/basicmachines-co/basic-memory:v0.16.0
-```
-
-## v0.15.2 (2025-10-14)
-
-### Features
-
- **#356**: Add WebDAV upload command for cloud projects
-  ([`5258f45`](https://github.com/basicmachines-co/basic-memory/commit/5258f457))
-  - New `bm cloud upload` command for uploading local files/directories to cloud projects
-  - WebDAV-based file transfer with automatic directory creation
-  - Support for `.gitignore` and `.bmignore` pattern filtering
-  - Automatic project creation with `--create-project` flag
-  - Optional post-upload sync with `--sync` flag (enabled by default)
-  - Human-readable file size reporting (bytes, KB, MB)
-  - Comprehensive test coverage (28 unit tests)
-
-### Migration Guide
-
-No manual migration required. Upgrade with:
-
-```bash
-# Update via uv
-uv tool upgrade basic-memory
-
-# Or install fresh
-uv tool install basic-memory
-```
-
-**What's New:**
- Upload local files to cloud projects with `bm cloud upload`
- Streamlined cloud project creation and management
- Better file filtering with gitignore integration
-
-### Installation
-
-```bash
-# Latest stable release
-uv tool install basic-memory
-
-# Update existing installation
-uv tool upgrade basic-memory
-
-# Docker
-docker pull ghcr.io/basicmachines-co/basic-memory:v0.15.2
-```
-
-## v0.15.1 (2025-10-13)
-
-### Performance Improvements
-
- **#352**: Optimize sync/indexing for 43% faster performance
-  ([`c0538ad`](https://github.com/basicmachines-co/basic-memory/commit/c0538ad2perf0d68a2a3604e255c3f2c42c5ed))
-  - Significant performance improvements to file synchronization and indexing operations
-  - 43% reduction in sync time for large knowledge bases
-  - Optimized database queries and file processing
-
- **#350**: Optimize directory operations for 10-100x performance improvement
-  ([`00b73b0`](https://github.com/basicmachines-co/basic-memory/commit/00b73b0d))
-  - Dramatic performance improvements for directory listing operations
-  - 10-100x faster directory traversal depending on knowledge base size
-  - Reduced memory footprint for large directory structures
-  - Exclude null fields from directory endpoint responses for smaller payloads
-
-### Bug Fixes
-
- **#355**: Update view_note and ChatGPT tools for Claude Desktop compatibility
-  ([`2b7008d`](https://github.com/basicmachines-co/basic-memory/commit/2b7008d9))
-  - Fix view_note tool formatting for better Claude Desktop rendering
-  - Update ChatGPT tool integration for improved compatibility
-  - Enhanced artifact display in Claude Desktop interface
-
- **#348**: Add permalink normalization to project lookups in deps.py
-  ([`a09066e`](https://github.com/basicmachines-co/basic-memory/commit/a09066e0))
-  - Fix project lookup failures due to case sensitivity
-  - Normalize permalinks consistently across project operations
-  - Improve project switching reliability
-
- **#345**: Project deletion failing with permalink normalization
-  ([`be352ab`](https://github.com/basicmachines-co/basic-memory/commit/be352ab4))
-  - Fix project deletion errors related to permalink handling
-  - Ensure proper cleanup of project resources
-  - Improve error messages for deletion failures
-
- **#341**: Correct ProjectItem.home property to return path instead of name
-  ([`3e876a7`](https://github.com/basicmachines-co/basic-memory/commit/3e876a75))
-  - Fix ProjectItem.home to return correct project path
-  - Resolve configuration issues with project paths
-  - Improve project path resolution consistency
-
- **#339**: Prevent nested project paths to avoid data conflicts
-  ([`795e339`](https://github.com/basicmachines-co/basic-memory/commit/795e3393))
-  - Block creation of nested project paths that could cause data conflicts
-  - Add validation to prevent project path hierarchy issues
-  - Improve error messages for invalid project configurations
-
- **#338**: Normalize paths to lowercase in cloud mode to prevent case collisions
-  ([`07e304c`](https://github.com/basicmachines-co/basic-memory/commit/07e304ce))
-  - Fix path case sensitivity issues in cloud deployments
-  - Normalize paths consistently across cloud operations
-  - Prevent data loss from case-insensitive filesystem collisions
-
- **#336**: Cloud mode path validation and sanitization (bmc-issue-103)
-  ([`2a1c06d`](https://github.com/basicmachines-co/basic-memory/commit/2a1c06d9))
-  - Enhanced path validation for cloud deployments
-  - Improved path sanitization to prevent security issues
-  - Better error handling for invalid paths in cloud mode
-
- **#332**: Cloud mode path validation and sanitization
-  ([`7616b2b`](https://github.com/basicmachines-co/basic-memory/commit/7616b2bb))
-  - Additional cloud mode path fixes and improvements
-  - Comprehensive path validation for cloud environments
-  - Security enhancements for path handling
-
-### Features
-
- **#344**: Async client context manager pattern for cloud consolidation (SPEC-16)
-  ([`8d2e70c`](https://github.com/basicmachines-co/basic-memory/commit/8d2e70cf))
-  - Refactor async client to use context manager pattern
-  - Improve resource management and cleanup
-  - Enable better dependency injection for cloud deployments
-  - Foundation for cloud platform consolidation
-
- **#343**: Add SPEC-15 for configuration persistence via Tigris
-  ([`53438d1`](https://github.com/basicmachines-co/basic-memory/commit/53438d1e))
-  - Design specification for persistent configuration storage
-  - Foundation for cloud configuration management
-  - Tigris S3-compatible storage integration planning
-
- **#334**: Introduce BASIC_MEMORY_PROJECT_ROOT for path constraints
-  ([`ccc4386`](https://github.com/basicmachines-co/basic-memory/commit/ccc43866))
-  - Add environment variable for constraining project paths
-  - Improve security by limiting project creation locations
-  - Better control over project directory structure
-
-### Documentation
-
- **#335**: v0.15.0 assistant guide updates
-  ([`c6f93a0`](https://github.com/basicmachines-co/basic-memory/commit/c6f93a02))
-  - Update AI assistant guide for v0.15.0 features
-  - Improve documentation for new MCP tools
-  - Better examples and usage patterns
-
- **#339**: Add tool use documentation to write_note for root folder usage
-  ([`73202d1`](https://github.com/basicmachines-co/basic-memory/commit/73202d1a))
-  - Document how to use empty string for root folder in write_note
-  - Clarify folder parameter usage
-  - Improve tool documentation clarity
-
- Fix link in ai_assistant_guide resource
-  ([`2a1c06d`](https://github.com/basicmachines-co/basic-memory/commit/2a1c06d9))
-  - Correct broken documentation links
-  - Improve resource accessibility
-
-### Refactoring
-
- Add SPEC-17 and SPEC-18 documentation
-  ([`962d88e`](https://github.com/basicmachines-co/basic-memory/commit/962d88ea))
-  - New specification documents for future features
-  - Architecture planning and design documentation
-
-### Breaking Changes
-
-**None** - This release maintains full backward compatibility with v0.15.0
-
-### Migration Guide
-
-No manual migration required. Upgrade with:
-
-```bash
-# Update via uv
-uv tool upgrade basic-memory
-
-# Or install fresh
-uv tool install basic-memory
-```
-
-**What's Fixed:**
- Significant performance improvements (43% faster sync, 10-100x faster directory operations)
- Multiple cloud deployment stability fixes
- Project path validation and normalization issues resolved
- Better Claude Desktop and ChatGPT integration
-
-**What's New:**
- Context manager pattern for async clients (foundation for cloud consolidation)
- BASIC_MEMORY_PROJECT_ROOT environment variable for path constraints
- Enhanced cloud mode path handling and security
- SPEC-15 and SPEC-16 architecture documentation
-
-### Installation
-
-```bash
-# Latest stable release
-uv tool install basic-memory
-
-# Update existing installation
-uv tool upgrade basic-memory
-
-# Docker
-docker pull ghcr.io/basicmachines-co/basic-memory:v0.15.1
-```
-
-## v0.15.0 (2025-10-04)
-
-### Critical Bug Fixes
-
- **Permalink Collision Data Loss Prevention** - Fixed critical bug where creating similar entity names would overwrite existing files
-  ([`2a050ed`](https://github.com/basicmachines-co/basic-memory/commit/2a050edee42b07294f5199902a60b626bfc47be8))
-  - **Issue**: Creating "Node C" would overwrite "Node A.md" due to fuzzy search incorrectly matching similar file paths
-  - **Solution**: Added `strict=True` parameter to link resolution, disabling fuzzy search fallback during entity creation
-  - **Impact**: Prevents data loss from false positive path matching like "edge-cases/Node A.md" vs "edge-cases/Node C.md"
-  - **Testing**: Comprehensive integration tests and MCP-level permalink collision tests added
-  - **Status**: Manually verified fix prevents file overwrite in production scenarios
-
-### Bug Fixes
-
- **#330**: Remove .env file loading from BasicMemoryConfig
-  ([`f3b1945`](https://github.com/basicmachines-co/basic-memory/commit/f3b1945e4c0070d0282eaf98c085ef188c8edd2d))
-  - Clean up configuration initialization to prevent unintended environment variable loading
-
- **#329**: Normalize underscores in memory:// URLs for build_context
-  ([`f5a11f3`](https://github.com/basicmachines-co/basic-memory/commit/f5a11f3911edda55bee6970ed9e7c38f7fd7a059))
-  - Fix URL normalization to handle underscores consistently in memory:// protocol
-  - Improve knowledge graph navigation with standardized URL handling
-
- **#328**: Simplify entity upsert to use database-level conflict resolution
-  ([`ee83b0e`](https://github.com/basicmachines-co/basic-memory/commit/ee83b0e5a8f00cdcc8e24a0f8c9449c6eaddf649))
-  - Leverage SQLite's native UPSERT for cleaner entity creation/update logic
-  - Reduce application-level complexity by using database conflict resolution
-
- **#312**: Add proper datetime JSON schema format annotations for MCP validation
-  ([`a7bf42e`](https://github.com/basicmachines-co/basic-memory/commit/a7bf42ef495a3e2c66230985c3445cab5c52c408))
-  - Fix MCP schema validation errors with proper datetime format annotations
-  - Ensure compatibility with strict MCP schema validators
-
- **#281**: Fix move_note without file extension
-  ([`3e168b9`](https://github.com/basicmachines-co/basic-memory/commit/3e168b98f3962681799f4537eb86ded47e771665))
-  - Allow moving notes by title alone without requiring .md extension
-  - Improve move operation usability and error handling
-
- **#310**: Remove obsolete update_current_project function and --project flag reference
-  ([`17a6733`](https://github.com/basicmachines-co/basic-memory/commit/17a6733c9d280def922e37c2cd171e3ee44fce21))
-  - Clean up deprecated project management code
-  - Remove unused CLI flag references
-
- **#309**: Make sync operations truly non-blocking with thread pool
-  ([`1091e11`](https://github.com/basicmachines-co/basic-memory/commit/1091e113227c86f10f574e56a262aff72f728113))
-  - Move sync operations to background thread pool for improved responsiveness
-  - Prevent blocking during file synchronization operations
-
-### Features
-
- **#327**: CLI Subscription Validation (SPEC-13 Phase 2)
-  ([`ace6a0f`](https://github.com/basicmachines-co/basic-memory/commit/ace6a0f50d8d0b4ea31fb526361c2d9616271740))
-  - Implement subscription validation for CLI operations
-  - Foundation for future cloud billing integration
-
- **#322**: Cloud CLI sync via rclone bisync
-  ([`99a35a7`](https://github.com/basicmachines-co/basic-memory/commit/99a35a7fb410ef88c50050e666e4244350e44a6e))
-  - Add bidirectional cloud synchronization using rclone
-  - Enable local-cloud file sync with conflict detection
-
- **#315**: Implement SPEC-11 API performance optimizations
-  ([`5da97e4`](https://github.com/basicmachines-co/basic-memory/commit/5da97e482052907d68a2a3604e255c3f2c42c5ed))
-  - Comprehensive API performance improvements
-  - Optimized database queries and response times
-
- **#314**: Integrate ignore_utils to skip .gitignored files in sync process
-  ([`33ee1e0`](https://github.com/basicmachines-co/basic-memory/commit/33ee1e0831d2060587de2c9886e74ff111b04583))
-  - Respect .gitignore patterns during file synchronization
-  - Prevent syncing build artifacts and temporary files
-
- **#313**: Add disable_permalinks config flag
-  ([`9035913`](https://github.com/basicmachines-co/basic-memory/commit/903591384dffeba9996a18463818bdb8b28ca03e))
-  - Optional permalink generation for users who don't need them
-  - Improves flexibility for different knowledge management workflows
-
- **#306**: Implement cloud mount CLI commands for local file access
-  ([`2c5c606`](https://github.com/basicmachines-co/basic-memory/commit/2c5c606a394ab994334c8fd307b30370037bbf39))
-  - Mount cloud files locally using rclone for real-time editing
-  - Three performance profiles: fast (5s), balanced (10-15s), safe (15s+)
-  - Cross-platform rclone installer with package manager fallbacks
-
- **#305**: ChatGPT tools for search and fetch
-  ([`f40ab31`](https://github.com/basicmachines-co/basic-memory/commit/f40ab31685a9510a07f5d87bf24436c0df80680f))
-  - Add ChatGPT-specific search and fetch tools
-  - Expand AI assistant integration options
-
- **#298**: Implement SPEC-6 Stateless Architecture for MCP Tools
-  ([`a1d7792`](https://github.com/basicmachines-co/basic-memory/commit/a1d7792bdb6f71c4943b861d1c237f6ac7021247))
-  - Redesign MCP tools for stateless operation
-  - Enable cloud deployment with better scalability
-
- **#296**: Basic Memory cloud upload
-  ([`e0d8aeb`](https://github.com/basicmachines-co/basic-memory/commit/e0d8aeb14913f3471b9716d0c60c61adb1d74687))
-  - Implement file upload capabilities for cloud storage
-  - Foundation for cloud-hosted Basic Memory instances
-
- **#291**: Merge Cloud auth
-  ([`3a6baf8`](https://github.com/basicmachines-co/basic-memory/commit/3a6baf80fc6012e9434e06b1605f9a8b198d8688))
-  - OAuth 2.1 authentication with Supabase integration
-  - JWT-based tenant isolation for multi-user cloud deployments
-
-### Platform & Infrastructure
-
- **#331**: Add Python 3.13 to test matrix
-  ([`16d7edd`](https://github.com/basicmachines-co/basic-memory/commit/16d7eddbf704abfe53373663e80d05ecdde15aa7))
-  - Ensure compatibility with latest Python version
-  - Expand CI/CD testing coverage
-
- **#316**: Enable WAL mode and add Windows-specific SQLite optimizations
-  ([`c83d567`](https://github.com/basicmachines-co/basic-memory/commit/c83d567917267bb3d52708f4b38d2daf36c1f135))
-  - Enable Write-Ahead Logging for better concurrency
-  - Platform-specific SQLite optimizations for Windows users
-
- **#320**: Rework lifecycle management to optimize cloud deployment
-  ([`ea2e93d`](https://github.com/basicmachines-co/basic-memory/commit/ea2e93d9265bfa366d2d3796f99f579ab2aed48c))
-  - Optimize application lifecycle for cloud environments
-  - Improve startup time and resource management
-
- **#319**: Resolve entity relations in background to prevent cold start blocking
-  ([`324844a`](https://github.com/basicmachines-co/basic-memory/commit/324844a670d874410c634db520a68c09149045ea))
-  - Move relation resolution to background processing
-  - Faster MCP server cold starts
-
- **#318**: Enforce minimum 1-day timeframe for recent_activity
-  ([`f818702`](https://github.com/basicmachines-co/basic-memory/commit/f818702ab7f8d2d706178e7b0ed3467501c9c4a2))
-  - Fix timezone-related issues in recent activity queries
-  - Ensure consistent behavior across time zones
-
- **#317**: Critical cloud deployment fixes for MCP stability
-  ([`2efd8f4`](https://github.com/basicmachines-co/basic-memory/commit/2efd8f44e2d0259079ed5105fea34308875c0e10))
-  - Multiple stability improvements for cloud-hosted MCP servers
-  - Enhanced error handling and recovery
-
-### Technical Improvements
-
- **Comprehensive Testing** - Extensive test coverage for critical fixes
-  - New permalink collision test suite with 4 MCP-level integration tests
-  - Entity service test coverage expanded to reproduce fuzzy search bug
-  - Manual testing verification of data loss prevention
-  - All 55 entity service tests passing with new strict resolution
-
- **Windows Support Enhancements**
-  ([`7a8b08d`](https://github.com/basicmachines-co/basic-memory/commit/7a8b08d11ee627b54af6f5ea7ab4ef9fcd8cf4ed),
-   [`9aa4024`](https://github.com/basicmachines-co/basic-memory/commit/9aa40246a8ad1c3cef82b32e1ca7ce8ea23e1e05))
-  - Fix Windows test failures and add Windows CI support
-  - Address platform-specific issues for Windows users
-  - Enhanced cross-platform compatibility
-
- **Docker Improvements**
-  ([`105bcaa`](https://github.com/basicmachines-co/basic-memory/commit/105bcaa025576a06f889183baded6c18f3782696))
-  - Implement non-root Docker container to fix file ownership issues
-  - Improved security and compatibility in containerized deployments
-
- **Code Quality**
-  - Enhanced filename sanitization with optional kebab case support
-  - Improved character conflict detection for sync operations
-  - Better error handling across the codebase
-  - Path traversal security vulnerability fixes
-
-### Documentation
-
- **#321**: Corrected dead links in README
-  ([`fc38877`](https://github.com/basicmachines-co/basic-memory/commit/fc38877008cd8c762116f7ff4b2573495b4e5c0f))
-  - Fix broken documentation links
-  - Improve navigation and accessibility
-
- **#308**: Update Claude Code GitHub Workflow
-  ([`8c7e29e`](https://github.com/basicmachines-co/basic-memory/commit/8c7e29e325f36a67bdefe8811637493bef4bbf56))
-  - Enhanced GitHub integration documentation
-  - Better Claude Code collaboration workflow
-
-### Breaking Changes
-
-**None** - This release maintains full backward compatibility with v0.14.x
-
-All changes are either:
- Bug fixes that correct unintended behavior
- New optional features that don't affect existing functionality
- Internal optimizations that are transparent to users
-
-### Migration Guide
-
-No manual migration required. Upgrade with:
-
-```bash
-# Update via uv
-uv tool upgrade basic-memory
-
-# Or install fresh
-uv tool install basic-memory
-```
-
-**What's Fixed:**
- Data loss bug from permalink collisions is completely resolved
- Cloud deployment stability significantly improved
- Windows platform compatibility enhanced
- Better performance across all operations
-
-**What's New:**
- Cloud sync capabilities via rclone
- Subscription validation foundation
- Python 3.13 support
- Enhanced security and stability
-
-### Installation
-
-```bash
-# Latest stable release
-uv tool install basic-memory
-
-# Update existing installation
-uv tool upgrade basic-memory
-
-# Docker
-docker pull ghcr.io/basicmachines-co/basic-memory:v0.15.0
-```
-
 ## v0.14.2 (2025-07-03)

 ### Bug Fixes
@@ -2039,4 +1356,4 @@ Co-authored-by: phernandez <phernandez@basicmachines.co>
 ### Chores

 - Remove basic-foundation src ref in pyproject.toml
-  ([`29fce8b`](https://github.com/basicmachines-co/basic-memory/commit/29fce8b0b922d54d7799bf2534107ee6cfb961b8))
+  ([`29fce8b`](https://github.com/basicmachines-co/basic-memory/commit/29fce8b0b922d54d7799bf2534107ee6cfb961b8))
@@ -14,34 +14,20 @@ 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 (with coverage): `just test` - Runs both unit and integration tests with unified coverage
- Run unit tests only: `just test-unit` - Fast, no coverage
- Run integration tests only: `just test-int` - Fast, no coverage
- Generate HTML coverage: `just coverage` - Opens in browser
+- Install: `make install` or `pip install -e ".[dev]"`
+- Run tests: `uv run pytest -p pytest_mock -v` or `make test`
 - 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)
-
-### 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`
+- Lint: `make lint` or `ruff check . --fix`
+- Type check: `make type-check` or `uv run pyright`
+- Format: `make format` or `uv run ruff format .`
+- Run all code checks: `make check` (runs lint, format, type-check, test)
+- Create db migration: `make migration m="Your migration message"`
+- Run development MCP Inspector: `make run-inspector`

 ### Code Style Guidelines

 - Line length: 100 characters max
- Python 3.12+ with full type annotations (uses type parameters and type aliases)
+- Python 3.12+ with full type annotations
 - Format with ruff (consistent styling)
 - Import order: standard lib, third-party, local imports
 - Naming: snake_case for functions/variables, PascalCase for classes
@@ -75,46 +61,9 @@ See the [README.md](README.md) file for a project overview.
 - 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
 - Test database uses in-memory SQLite
- Each test runs in a standalone environment with in-memory SQLite and tmp_file directory
- 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
-
-### 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.
+- Avoid creating mocks in tests in most circumstances.
+- Each test runs in a standalone environment with in memory SQLite and tmp_file directory

 ## BASIC MEMORY PRODUCT USAGE

@@ -131,7 +80,6 @@ See SPEC-16 for full context manager refactor details.

 ### Basic Memory Commands

-**Local Commands:**
 - Sync knowledge: `basic-memory sync` or `basic-memory sync --watch`
 - Import from Claude: `basic-memory import claude conversations`
 - Import from ChatGPT: `basic-memory import chatgpt`
@@ -141,41 +89,24 @@ See SPEC-16 for full context manager refactor details.
    - Guide: `basic-memory tools basic-memory-guide`
    - Continue: `basic-memory tools continue-conversation --topic="search"`

-**Cloud Commands (requires subscription):**
- Authenticate: `basic-memory cloud login`
- Logout: `basic-memory cloud logout`
- Bidirectional sync: `basic-memory cloud sync`
- Integrity check: `basic-memory cloud check`
- Mount cloud storage: `basic-memory cloud mount`
- Unmount cloud storage: `basic-memory cloud unmount`
-
 ### 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
+    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph
+      awareness
+    - `read_file(path)` - Read raw file content (text, images, binaries) without knowledge graph processing

  **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
+    - `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")

  **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
-    - `get_current_project()` - Get current project information and stats
-    - `sync_status()` - Check file synchronization and background operation status
+    - `search(query, page, page_size)` - Full-text search across all content with filtering options

  **Visualization:**
    - `canvas(nodes, edges, title, folder)` - Generate Obsidian canvas files for knowledge graph visualization
@@ -187,34 +118,6 @@ See SPEC-16 for full context manager refactor details.
    - `recent_activity(timeframe)` - View recently changed items with formatted output
    - `json_canvas_spec()` - Full JSON Canvas specification for Obsidian visualization

-### 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
@@ -265,4 +168,4 @@ With GitHub integration, the development workflow includes:
 3. **Branch management** - Claude can create feature branches for implementations
 4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves

-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.
+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.
@@ -34,18 +34,11 @@ project and how to get started as a developer.

 4. **Run the Tests**:
   ```bash
-   # Run all tests with unified coverage (unit + integration)
+   # Run all tests
   just test
-
-   # Run unit tests only (fast, no coverage)
-   just test-unit
-
-   # Run integration tests only (fast, no coverage)
-   just test-int
-
-   # Generate HTML coverage report
-   just coverage
-
+   # or
+   uv run pytest -p pytest_mock -v
+   
   # Run a specific test
   pytest tests/path/to/test_file.py::test_function_name
   ```
@@ -141,7 +134,7 @@ agreement to the DCO.

 ## Code Style Guidelines

- **Python Version**: Python 3.12+ with full type annotations (3.12+ required for type parameter syntax)
+- **Python Version**: Python 3.12+ with full type annotations
 - **Line Length**: 100 characters maximum
 - **Formatting**: Use ruff for consistent styling
 - **Import Order**: Standard lib, third-party, local imports
@@ -151,78 +144,12 @@ agreement to the DCO.

 ## Testing Guidelines

-### Test Structure
-
-Basic Memory uses two test directories with unified coverage reporting:
-
- **`tests/`**: Unit tests that test individual components in isolation
-  - Fast execution with extensive mocking
-  - Test individual functions, classes, and modules
-  - Run with: `just test-unit` (no coverage, fast)
-
- **`test-int/`**: Integration tests that test real-world scenarios
-  - Test full workflows with real database and file operations
-  - Include performance benchmarks
-  - More realistic but slower than unit tests
-  - Run with: `just test-int` (no coverage, fast)
-
-### Running Tests
-
-```bash
-# Run all tests with unified coverage report
-just test
-
-# Run only unit tests (fast iteration)
-just test-unit
-
-# Run only integration tests
-just test-int
-
-# Generate HTML coverage report
-just coverage
-
-# Run specific test
-pytest tests/path/to/test_file.py::test_function_name
-
-# Run tests excluding benchmarks
-pytest -m "not benchmark"
-
-# Run only benchmark tests
-pytest -m benchmark test-int/test_sync_performance_benchmark.py
-```
-
-### Performance Benchmarks
-
-The `test-int/test_sync_performance_benchmark.py` file contains performance benchmarks that measure sync and indexing speed:
-
- `test_benchmark_sync_100_files` - Small repository performance
- `test_benchmark_sync_500_files` - Medium repository performance
- `test_benchmark_sync_1000_files` - Large repository performance (marked slow)
- `test_benchmark_resync_no_changes` - Re-sync performance baseline
-
-Run benchmarks with:
-```bash
-# Run all benchmarks (excluding slow ones)
-pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"
-
-# Run all benchmarks including slow ones
-pytest test-int/test_sync_performance_benchmark.py -v -m benchmark
-
-# Run specific benchmark
-pytest test-int/test_sync_performance_benchmark.py::test_benchmark_sync_100_files -v
-```
-
-See `test-int/BENCHMARKS.md` for detailed benchmark documentation.
-
-### Testing Best Practices
-
- **Coverage Target**: We aim for high test coverage for all code
+- **Coverage Target**: We aim for 100% test coverage for all code
 - **Test Framework**: Use pytest for unit and integration tests
- **Mocking**: Avoid mocking in integration tests; use sparingly in unit tests
+- **Mocking**: Use pytest-mock for mocking dependencies only when necessary
 - **Edge Cases**: Test both normal operation and edge cases
 - **Database Testing**: Use in-memory SQLite for testing database operations
 - **Fixtures**: Use async pytest fixtures for setup and teardown
- **Markers**: Use `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests

 ## Release Process

@@ -24,12 +24,11 @@ WORKDIR /app
 RUN uv sync --locked

 # Create necessary directories and set ownership
-RUN mkdir -p /app/data/basic-memory /app/.basic-memory && \
+RUN mkdir -p /app/data /app/.basic-memory && \
    chown -R appuser:${GID} /app

 # Set default data directory and add venv to PATH
-ENV BASIC_MEMORY_HOME=/app/data/basic-memory \
-    BASIC_MEMORY_PROJECT_ROOT=/app/data \
+ENV BASIC_MEMORY_HOME=/app/data \
    PATH="/app/.venv/bin:$PATH"

 # Switch to the non-root user
@@ -7,16 +7,6 @@
 ![](https://badge.mcpx.dev?type=dev 'MCP Dev')
 [![smithery badge](https://smithery.ai/badge/@basicmachines-co/basic-memory)](https://smithery.ai/server/@basicmachines-co/basic-memory)

-## 🚀 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.
-
-[Sign up now →](https://basicmemory.com/beta)
-
-with a 7 day free trial
-
 # Basic Memory

 Basic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like
@@ -110,9 +100,6 @@ With Basic Memory, you can:
 - Keep everything local and under your control
 - Use familiar tools like Obsidian to view and edit notes
 - Build a personal knowledge base that grows over time
- Sync your knowledge to the cloud with bidirectional synchronization
- Authenticate and manage cloud projects with subscription validation
- Mount cloud storage for direct file access

 ## How It Works in Practice

@@ -359,57 +346,14 @@ basic-memory sync
 basic-memory sync --watch
 ```

-3. Cloud features (optional, requires subscription):
+3. In Claude Desktop, the LLM can now use these tools:

-```bash
-# Authenticate with cloud
-basic-memory cloud login
-
-# Bidirectional sync with cloud
-basic-memory cloud sync
-
-# Verify cloud integrity
-basic-memory cloud check
-
-# Mount cloud storage
-basic-memory cloud mount
-```
-
-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
-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
-```
-
-**Knowledge Graph Navigation:**
-```
 build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
-recent_activity(type, depth, timeframe) - 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
-```
-
-**Project Management:**
-```
-list_memory_projects() - List all available projects
-create_memory_project(project_name, project_path) - Create new projects
-get_current_project() - Show current project stats
-sync_status() - Check synchronization status
-```
-
-**Visualization:**
-```
+recent_activity(type, depth, timeframe) - Find recently updated information
 canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 ```

@@ -427,62 +371,10 @@ canvas(nodes, edges, title, folder) - Generate knowledge visualizations

 See the [Documentation](https://memory.basicmachines.co/) 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)
-
-## Development
-
-### Running Tests
-
-Basic Memory supports dual database backends (SQLite and Postgres). Tests are parametrized to run against both backends automatically.
-
-**Quick Start:**
-```bash
-# Run SQLite tests (default, no Docker needed)
-just test-sqlite
-
-# Run Postgres tests (requires Docker)
-just test-postgres
-```
-
-**Available Test Commands:**
-
- `just test-sqlite` - Run tests against SQLite only (fastest, no Docker needed)
- `just test-postgres` - Run tests against Postgres only (requires Docker)
- `just test-windows` - Run Windows-specific tests (auto-skips on other platforms)
- `just test-benchmark` - Run performance benchmark tests
- `just test-all` - Run all tests including Windows, Postgres, and benchmarks
-
-**Postgres Testing Requirements:**
-
-To run Postgres tests, you need to start the test database:
-```bash
-docker-compose -f docker-compose-postgres.yml up -d
-```
-
-Tests will connect to `localhost:5433/basic_memory_test`.
-
-**Test Markers:**
-
-Tests use pytest markers for selective execution:
- `postgres` - Tests that run against Postgres backend
- `windows` - Windows-specific database optimizations
- `benchmark` - Performance tests (excluded from default runs)
-
-**Other Development Commands:**
-```bash
-just install          # Install with dev dependencies
-just lint             # Run linting checks
-just typecheck        # Run type checking
-just format           # Format code with ruff
-just check            # Run all quality checks
-just migration "msg"  # Create database migration
-```
-
-See the [justfile](justfile) for the complete list of development commands.
+- [Complete User Guide](https://memory.basicmachines.co/docs/user-guide)
+- [CLI tools](https://memory.basicmachines.co/docs/cli-reference)
+- [Managing multiple Projects](https://memory.basicmachines.co/docs/cli-reference#project)
+- [Importing data from OpenAI/Claude Projects](https://memory.basicmachines.co/docs/cli-reference#import)

 ## License

@@ -501,4 +393,4 @@ and submitting PRs.
 </picture>
 </a>

-Built with ♥️ by Basic Machines
+Built with ♥️ by Basic Machines
@@ -1,42 +0,0 @@
-# Docker Compose configuration for Basic Memory with PostgreSQL
-# Use this for local development and testing with Postgres backend
-#
-# Usage:
-#   docker-compose -f docker-compose-postgres.yml up -d
-#   docker-compose -f docker-compose-postgres.yml down
-
-services:
-  postgres:
-    image: postgres:17
-    container_name: basic-memory-postgres
-    environment:
-      # Local development/test credentials - NOT for production
-      # These values are referenced by tests and justfile commands
-      POSTGRES_DB: basic_memory
-      POSTGRES_USER: basic_memory_user
-      POSTGRES_PASSWORD: dev_password  # Simple password for local testing only
-    ports:
-      - "5433:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U basic_memory_user -d basic_memory"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    restart: unless-stopped
-
-volumes:
-  # Named volume for Postgres data
-  postgres_data:
-    driver: local
-
-  # Named volume for persistent configuration
-  # Database will be stored in Postgres, not in this volume
-  basic-memory-config:
-    driver: local
-
-# Network configuration (optional)
-# networks:
-#   basic-memory-net:
-#     driver: bridge
@@ -2,95 +2,28 @@

 # Install dependencies
 install:
-    uv pip install -e ".[dev]"
+    pip install -e ".[dev]"
    uv sync
    @echo ""
    @echo "💡 Remember to activate the virtual environment by running: source .venv/bin/activate"

-# Run all tests with unified coverage report
-test: test-unit test-int
-
-# Run unit tests only (fast, no coverage)
+# Run unit tests in parallel
 test-unit:
-    uv run pytest -p pytest_mock -v --no-cov tests
+    uv run pytest -p pytest_mock -v -n auto

-# Run integration tests only (fast, no coverage)
+# Run integration tests in parallel
 test-int:
-    uv run pytest -p pytest_mock -v --no-cov test-int
+    uv run pytest -p pytest_mock -v --no-cov -n auto test-int

-# ==============================================================================
-# DATABASE BACKEND TESTING
-# ==============================================================================
-# Basic Memory supports dual database backends (SQLite and Postgres).
-# Tests are parametrized to run against both backends automatically.
-#
-# Quick Start:
-#   just test-sqlite    # Run SQLite tests (default, no Docker needed)
-#   just test-postgres  # Run Postgres tests (requires Docker)
-#
-# For Postgres tests, first start the database:
-#   docker-compose -f docker-compose-postgres.yml up -d
-# ==============================================================================
-
-# Run tests against SQLite only (default backend, skip Postgres/Benchmark tests)
-# This is the fastest option and doesn't require any Docker setup.
-# Use this for local development and quick feedback.
-# Includes Windows-specific tests which will auto-skip on non-Windows platforms.
-test-sqlite:
-    uv run pytest -p pytest_mock -v --no-cov -m "not postgres and not benchmark" tests test-int
-
-# Run tests against Postgres only (requires docker-compose-postgres.yml up)
-# First start Postgres: docker-compose -f docker-compose-postgres.yml up -d
-# Tests will connect to localhost:5433/basic_memory_test
-# To reset the database: just postgres-reset
-test-postgres:
-    uv run pytest -p pytest_mock -v --no-cov -m "postgres and not benchmark" tests test-int
-
-# 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
-postgres-reset:
-    docker exec basic-memory-postgres psql -U ${POSTGRES_USER:-basic_memory_user} -d ${POSTGRES_TEST_DB:-basic_memory_test} -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
-    @echo "✅ Postgres test database reset"
-
-# Run Alembic migrations manually against Postgres test database
-# Useful for debugging migration issues
-# Uses credentials from docker-compose-postgres.yml (can override with env vars)
-postgres-migrate:
-    @cd src/basic_memory/alembic && \
-    BASIC_MEMORY_DATABASE_BACKEND=postgres \
-    BASIC_MEMORY_DATABASE_URL=${POSTGRES_TEST_URL:-postgresql://basic_memory_user:dev_password@localhost:5433/basic_memory_test} \
-    uv run alembic upgrade head
-    @echo "✅ Migrations applied to Postgres test database"
-
-# Run Windows-specific tests only (only works on Windows platform)
-# 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
-
-# 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
-
-# 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
-
-# Generate HTML coverage report
-coverage:
-    uv run pytest -p pytest_mock -v -n auto tests test-int --cov-report=html
-    @echo "Coverage report generated in htmlcov/index.html"
+# Run all tests
+test: test-unit test-int

 # Lint and fix code (calls fix)
 lint: fix

 # Lint and fix code
 fix:
-    uv run ruff check --fix --unsafe-fixes src tests test-int
+    uv run ruff check --fix --unsafe-fixes src tests

 # Type check code
 typecheck:
@@ -3,7 +3,7 @@ name = "basic-memory"
 dynamic = ["version"]
 description = "Local-first knowledge management combining Zettelkasten with knowledge graphs"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.12.1"
 license = { text = "AGPL-3.0-or-later" }
 authors = [
    { name = "Basic Machines", email = "hello@basic-machines.co" }
@@ -34,9 +34,7 @@ dependencies = [
    "pyjwt>=2.10.1",
    "python-dotenv>=1.1.0",
    "pytest-aio>=1.9.0",
-    "aiofiles>=24.1.0", # Async file I/O
-    "logfire>=0.73.0", # Optional observability (disabled by default via config)
-    "asyncpg>=0.30.0",
+    "aiofiles>=24.1.0",  # Async file I/O
 ]


@@ -56,22 +54,16 @@ build-backend = "hatchling.build"
 [tool.pytest.ini_options]
 pythonpath = ["src", "tests"]
 addopts = "--cov=basic_memory --cov-report term-missing"
-testpaths = ["tests", "test-int"]
+testpaths = ["tests"]
 asyncio_mode = "strict"
 asyncio_default_fixture_loop_scope = "function"
-markers = [
-    "benchmark: Performance benchmark tests (deselect with '-m \"not benchmark\"')",
-    "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\"')",
-]

 [tool.ruff]
 line-length = 100
 target-version = "py312"

-[dependency-groups]
-dev = [
+[tool.uv]
+dev-dependencies = [
    "gevent>=24.11.1",
    "icecream>=2.1.3",
    "pytest>=8.3.4",
@@ -80,9 +72,6 @@ dev = [
    "pytest-asyncio>=0.24.0",
    "pytest-xdist>=3.0.0",
    "ruff>=0.1.6",
-    "freezegun>=1.5.5",
-    "nest-asyncio>=1.6.0",
-    "psycopg2-binary>=2.9.0",  # For Alembic migrations with Postgres
 ]

 [tool.hatch.version]
@@ -1,569 +0,0 @@
---
-title: 'SPEC-10: Unified Deployment Workflow and Event Tracking'
-type: spec
-permalink: specs/spec-10-unified-deployment-workflow-event-tracking
-tags:
- workflow
- deployment
- event-sourcing
- architecture
- simplification
---
-
-# SPEC-10: Unified Deployment Workflow and Event Tracking
-
-## Why
-
-We replaced a complex multi-workflow system with DBOS orchestration that was proving to be more trouble than it was worth. The previous architecture had four separate workflows (`tenant_provisioning`, `tenant_update`, `tenant_deployment`, `tenant_undeploy`) with overlapping logic, complex state management, and fragmented event tracking. DBOS added unnecessary complexity without providing sufficient value, leading to harder debugging and maintenance.
-
-**Problems Solved:**
- **Framework Complexity**: DBOS configuration overhead and fighting framework limitations
- **Code Duplication**: Multiple workflows implementing similar operations with duplicate logic
- **Poor Observability**: Fragmented event tracking across workflow boundaries
- **Maintenance Overhead**: Complex orchestration for fundamentally simple operations
- **Debugging Difficulty**: Framework abstractions hiding simple Python stack traces
-
-## What
-
-This spec documents the architectural simplification that consolidates tenant lifecycle management into a unified system with comprehensive event tracking.
-
-**Affected Areas:**
- Tenant deployment workflows (provisioning, updates, undeploying)
- Event sourcing and workflow tracking infrastructure
- API endpoints for tenant operations
- Database schema for workflow and event correlation
- Integration testing for tenant lifecycle operations
-
-**Key Changes:**
- **Removed DBOS entirely** - eliminated framework dependency and complexity
- **Consolidated 4 workflows → 2 unified deployment workflows (deploy/undeploy)**
- **Added workflow tracking system** with complete event correlation
- **Simplified API surface** - single `/deploy` endpoint handles all scenarios
- **Enhanced observability** through event sourcing with workflow grouping
-
-## How (High Level)
-
-### Architectural Philosophy
-**Embrace simplicity over framework complexity** - use well-structured Python with proper database design instead of complex orchestration frameworks.
-
-### Core Components
-
-#### 1. Unified Deployment Workflow
-```python
-class TenantDeploymentWorkflow:
-    async def deploy_tenant_workflow(self, tenant_id: str, workflow_id: UUID, image_tag: str = None):
-        # Single workflow handles both initial provisioning AND updates
-        # Each step is idempotent and handles its own error recovery
-        # Database transactions provide the durability we need
-        await self.start_deployment_step(workflow_id, tenant_uuid, image_tag)
-        await self.create_fly_app_step(workflow_id, tenant_uuid)
-        await self.create_bucket_step(workflow_id, tenant_uuid)
-        await self.deploy_machine_step(workflow_id, tenant_uuid, image_tag)
-        await self.complete_deployment_step(workflow_id, tenant_uuid, image_tag, deployment_time)
-```
-
-**Key Benefits:**
- **Handles both provisioning and updates** in single workflow
- **Idempotent operations** - safe to retry any step
- **Clean error handling** via simple Python exceptions
- **Resumable** - can restart from any failed step
-
-#### 2. Workflow Tracking System
-
-**Database Schema:**
-```sql
-CREATE TABLE workflow (
-    id UUID PRIMARY KEY,
-    workflow_type VARCHAR(50) NOT NULL,  -- 'tenant_deployment', 'tenant_undeploy'
-    tenant_id UUID REFERENCES tenant(id),
-    status VARCHAR(20) DEFAULT 'running', -- 'running', 'completed', 'failed'
-    workflow_metadata JSONB DEFAULT '{}'  -- image_tag, etc.
-);
-
-ALTER TABLE event ADD COLUMN workflow_id UUID REFERENCES workflow(id);
-```
-
-**Event Correlation:**
- Every workflow operation generates events tagged with `workflow_id`
- Complete audit trail from workflow start to completion
- Events grouped by workflow for easy reconstruction of operations
-
-#### 3. Parameter Standardization
-All workflow methods follow consistent signature pattern:
-```python
-async def method_name(self, session: AsyncSession, workflow_id: UUID | None, tenant_id: UUID, ...)
-```
-
-**Benefits:**
- **Consistent event tagging** - all events properly correlated
- **Clear method contracts** - workflow_id always first parameter
- **Type safety** - proper UUID handling throughout
-
-### Implementation Strategy
-
-#### Phase 1: Workflow Consolidation ✅ COMPLETED
- [x] **Remove DBOS dependency** - eliminated dbos_config.py and all DBOS imports
- [x] **Create unified TenantDeploymentWorkflow** - handles both provisioning and updates
- [x] **Remove legacy workflows** - deleted tenant_provisioning.py, tenant_update.py
- [x] **Simplify API endpoints** - consolidated to single `/deploy` endpoint
- [x] **Update integration tests** - comprehensive edge case testing
-
-#### Phase 2: Workflow Tracking System ✅ COMPLETED
- [x] **Database migration** - added workflow table and event.workflow_id foreign key
- [x] **Workflow repository** - CRUD operations for workflow records
- [x] **Event correlation** - all workflow events tagged with workflow_id
- [x] **Comprehensive testing** - workflow lifecycle and event grouping tests
-
-#### Phase 3: Parameter Standardization ✅ COMPLETED
- [x] **Standardize method signatures** - workflow_id as first parameter pattern
- [x] **Fix event tagging** - ensure all workflow events properly correlated
- [x] **Update service methods** - consistent parameter order across tenant_service
- [x] **Integration test validation** - verify complete event sequences
-
-### Architectural Benefits
-
-#### Code Simplification
- **39 files changed**: 2,247 additions, 3,256 deletions (net -1,009 lines)
- **Eliminated framework complexity** - no more DBOS configuration or abstractions
- **Consolidated logic** - single deployment workflow vs 4 separate workflows
- **Cleaner API surface** - unified endpoint vs multiple workflow-specific endpoints
-
-#### Enhanced Observability
- **Complete event correlation** - every workflow event tagged with workflow_id
- **Audit trail reconstruction** - can trace entire tenant lifecycle through events
- **Workflow status tracking** - running/completed/failed states in database
- **Comprehensive testing** - edge cases covered with real infrastructure
-
-#### Operational Benefits
- **Simpler debugging** - plain Python stack traces vs framework abstractions
- **Reduced dependencies** - one less complex framework to maintain
- **Better error handling** - explicit exception handling vs framework magic
- **Easier maintenance** - straightforward Python code vs orchestration complexity
-
-## How to Evaluate
-
-### Success Criteria
-
-#### Functional Completeness ✅ VERIFIED
- [x] **Unified deployment workflow** handles both initial provisioning and updates
- [x] **Undeploy workflow** properly integrated with event tracking
- [x] **All operations idempotent** - safe to retry any step without duplication
- [x] **Complete tenant lifecycle** - provision → active → update → undeploy
-
-#### Event Tracking and Correlation ✅ VERIFIED
- [x] **All workflow events tagged** with proper workflow_id
- [x] **Event sequence verification** - tests assert exact event order and content
- [x] **Workflow grouping** - events can be queried by workflow_id for complete audit trail
- [x] **Cross-workflow isolation** - deployment vs undeploy events properly separated
-
-#### Database Schema and Performance ✅ VERIFIED
- [x] **Migration applied** - workflow table and event.workflow_id column created
- [x] **Proper indexing** - performance optimized queries on workflow_type, tenant_id, status
- [x] **Foreign key constraints** - referential integrity between workflows and events
- [x] **Database triggers** - updated_at timestamp automation
-
-#### Test Coverage ✅ COMPREHENSIVE
- [x] **Unit tests**: 4 workflow tracking tests covering lifecycle and event grouping
- [x] **Integration tests**: Real infrastructure testing with Fly.io resources
- [x] **Edge case coverage**: Failed deployments, partial state recovery, resource conflicts
- [x] **Event sequence verification**: Exact event order and content validation
-
-### Testing Procedure
-
-#### Unit Test Validation ✅ PASSING
-```bash
-cd apps/cloud && pytest tests/test_workflow_tracking.py -v
-# 4/4 tests passing - workflow lifecycle and event grouping
-```
-
-#### Integration Test Validation ✅ PASSING
-```bash
-cd apps/cloud && pytest tests/integration/test_tenant_workflow_deployment_integration.py -v
-cd apps/cloud && pytest tests/integration/test_tenant_workflow_undeploy_integration.py -v
-# Comprehensive real infrastructure testing with actual Fly.io resources
-# Tests provision → deploy → update → undeploy → cleanup cycles
-```
-
-### Performance Metrics
-
-#### Code Metrics ✅ ACHIEVED
- **Net code reduction**: -1,009 lines (3,256 deletions, 2,247 additions)
- **Workflow consolidation**: 4 workflows → 1 unified deployment workflow
- **Dependency reduction**: Removed DBOS framework dependency entirely
- **API simplification**: Multiple endpoints → single `/deploy` endpoint
-
-#### Operational Metrics ✅ VERIFIED
- **Event correlation**: 100% of workflow events properly tagged with workflow_id
- **Audit trail completeness**: Full tenant lifecycle traceable through event sequences
- **Error handling**: Clean Python exceptions vs framework abstractions
- **Debugging simplicity**: Direct stack traces vs orchestration complexity
-
-### Implementation Status: ✅ COMPLETE
-
-All phases completed successfully with comprehensive testing and verification:
-
-**Phase 1 - Workflow Consolidation**: ✅ COMPLETE
- Removed DBOS dependency and consolidated workflows
- Unified deployment workflow handles all scenarios
- Comprehensive integration testing with real infrastructure
-
-**Phase 2 - Workflow Tracking**: ✅ COMPLETE
- Database schema implemented with proper indexing
- Event correlation system fully functional
- Complete audit trail capability verified
-
-**Phase 3 - Parameter Standardization**: ✅ COMPLETE
- Consistent method signatures across all workflow methods
- All events properly tagged with workflow_id
- Type safety verified across entire codebase
-
-**Phase 4 - Asynchronous Job Queuing**:
-**Goal**: Transform synchronous deployment workflows into background jobs for better user experience and system reliability.
-
-**Current Problem**:
- Deployment API calls are synchronous - users wait for entire tenant provisioning (30-60 seconds)
- No retry mechanism for failed operations
- HTTP timeouts on long-running deployments
- Poor user experience during infrastructure provisioning
-
-**Solution**: Redis-backed job queue with arq for reliable background processing
-
-#### Architecture Overview
-```python
-# API Layer: Return immediately with job tracking
-@router.post("/{tenant_id}/deploy")
-async def deploy_tenant(tenant_id: UUID):
-    # Create workflow record in Postgres
-    workflow = await workflow_repo.create_workflow("tenant_deployment", tenant_id)
-
-    # Enqueue job in Redis
-    job = await arq_pool.enqueue_job('deploy_tenant_task', tenant_id, workflow.id)
-
-    # Return job ID immediately
-    return {"job_id": job.job_id, "workflow_id": workflow.id, "status": "queued"}
-
-# Background Worker: Process via existing unified workflow
-async def deploy_tenant_task(ctx, tenant_id: str, workflow_id: str):
-    # Existing workflow logic - zero changes needed!
-    await workflow_manager.deploy_tenant(UUID(tenant_id), workflow_id=UUID(workflow_id))
-```
-
-#### Implementation Tasks
-
-**Phase 4.1: Core Job Queue Setup** ✅ COMPLETED
- [x] **Add arq dependency** - integrated Redis job queue with existing infrastructure
- [x] **Create job definitions** - wrapped existing deployment/undeploy workflows as arq tasks
- [x] **Update API endpoints** - updated provisioning endpoints to return job IDs instead of waiting for completion
- [x] **JobQueueService implementation** - service layer for job enqueueing and status tracking
- [x] **Job status tracking** - integrated with existing workflow table for status updates
- [x] **Comprehensive testing** - 18 tests covering positive, negative, and edge cases
-
-**Phase 4.2: Background Worker Implementation** ✅ COMPLETED
- [x] **Job status API** - GET /jobs/{job_id}/status endpoint integrated with JobQueueService
- [x] **Background worker process** - arq worker to process queued jobs with proper settings and Redis configuration
- [x] **Worker settings and configuration** - WorkerSettings class with proper timeouts, max jobs, and error handling
- [x] **Fix API endpoints** - updated job status API to use JobQueueService instead of direct Redis access
- [x] **Integration testing** - comprehensive end-to-end testing with real ARQ workers and Fly.io infrastructure
- [x] **Worker entry points** - dual-purpose entrypoint.sh script and __main__.py module support for both API and worker processes
- [x] **Test fixture updates** - fixed all API and service test fixtures to work with job queue dependencies
- [x] **AsyncIO event loop fixes** - resolved event loop issues in integration tests for subprocess worker compatibility
- [x] **Complete test coverage** - all 46 tests passing across unit, integration, and API test suites
- [x] **Type safety verification** - 0 type checking errors across entire ARQ job queue implementation
-
-#### Phase 4.2 Implementation Summary ✅ COMPLETE
-
-**Core ARQ Job Queue System:**
- **JobQueueService** - Centralized service for job enqueueing, status tracking, and Redis pool management
- **deployment_jobs.py** - ARQ job functions that wrap existing deployment/undeploy workflows
- **Worker Settings** - Production-ready ARQ configuration with proper timeouts and error handling
- **Dual-Process Architecture** - Single Docker image with entrypoint.sh supporting both API and worker modes
-
-**Key Files Added:**
- `apps/cloud/src/basic_memory_cloud/jobs/` - Complete job queue implementation (7 files)
- `apps/cloud/entrypoint.sh` - Dual-purpose Docker container entry point
- `apps/cloud/tests/integration/test_worker_integration.py` - Real infrastructure integration tests
- `apps/cloud/src/basic_memory_cloud/schemas/job_responses.py` - API response schemas
-
-**API Integration:**
- Provisioning endpoints return job IDs immediately instead of blocking for 60+ seconds
- Job status API endpoints for real-time monitoring of deployment progress
- Proper error handling and job failure scenarios with detailed error messages
-
-**Testing Achievement:**
- **46 total tests passing** across all test suites (unit, integration, API, services)
- **Real infrastructure testing** - ARQ workers process actual Fly.io deployments
- **Event loop safety** - Fixed asyncio issues for subprocess worker compatibility
- **Test fixture updates** - All fixtures properly support job queue dependencies
- **Type checking** - 0 errors across entire codebase
-
-**Technical Metrics:**
- **38 files changed** - +1,736 insertions, -334 deletions
- **Integration test runtime** - ~18 seconds with real ARQ workers and Fly.io verification
- **Event loop isolation** - Proper async session management for subprocess compatibility
- **Redis integration** - Production-ready Redis configuration with connection pooling
-
-**Phase 4.3: Production Hardening** ✅ COMPLETED
- [x] **Configure Upstash Redis** - production Redis setup on Fly.io
- [x] **Retry logic for external APIs** - exponential backoff for flaky Tigris IAM operations
- [x] **Monitoring and observability** - comprehensive Redis queue monitoring with CLI tools
- [x] **Error handling improvements** - graceful handling of expected API errors with appropriate log levels
- [x] **CLI tooling enhancements** - bulk update commands for CI/CD automation
- [x] **Documentation improvements** - comprehensive monitoring guide with Redis patterns
- [x] **Job uniqueness** - ARQ-based duplicate prevention for tenant operations
- [ ] **Worker scaling** - multiple arq workers for parallel job processing
- [ ] **Job persistence** - ensure jobs survive Redis/worker restarts
- [ ] **Error alerting** - notifications for failed deployment jobs
-
-**Phase 4.4: Advanced Features** (Future)
- [ ] **Job scheduling** - deploy tenants at specific times
- [ ] **Priority queues** - urgent deployments processed first
- [ ] **Batch operations** - bulk tenant deployments
- [ ] **Job dependencies** - deployment → configuration → activation chains
-
-#### Benefits Achieved ✅ REALIZED
-
-**User Experience Improvements:**
- **Immediate API responses** - users get job ID instantly vs waiting 60+ seconds for deployment completion
- **Real-time job tracking** - status API provides live updates on deployment progress
- **Better error visibility** - detailed error messages and job failure tracking
- **CI/CD automation ready** - bulk update commands for automated tenant deployments
-
-**System Reliability:**
- **Redis persistence** - jobs survive Redis/worker restarts with proper queue durability
- **Idempotent job processing** - jobs can be safely retried without side effects
- **Event loop isolation** - worker processes operate independently from API server
- **Retry resilience** - exponential backoff for flaky external API calls (3 attempts, 1s/2s delays)
- **Graceful error handling** - expected API errors logged at INFO level, unexpected at ERROR level
- **Job uniqueness** - prevent duplicate tenant operations with ARQ's built-in uniqueness feature
-
-**Operational Benefits:**
- **Horizontal scaling ready** - architecture supports adding more workers for parallel processing
- **Comprehensive testing** - real infrastructure integration tests ensure production reliability
- **Type safety** - full type checking prevents runtime errors in job processing
- **Clean separation** - API and worker processes use same codebase with different entry points
- **Queue monitoring** - Redis CLI integration for real-time queue activity monitoring
- **Comprehensive documentation** - detailed monitoring guide with Redis pattern explanations
-
-**Development Benefits:**
- **Zero workflow changes** - existing deployment/undeploy workflows work unchanged as background jobs
- **Async/await native** - modern Python asyncio patterns throughout the implementation
- **Event correlation preserved** - all existing workflow tracking and event sourcing continues to work
- **Enhanced CLI tooling** - unified tenant commands with proper endpoint routing
- **Database integrity** - proper foreign key constraint handling in tenant deletion
-
-#### Infrastructure Requirements
- **Local**: Redis via docker-compose (already exists) ✅
- **Production**: Upstash Redis on Fly.io (already configured) ✅
- **Workers**: arq worker processes (new deployment target)
- **Monitoring**: Job status dashboard (simple web interface)
-
-#### API Evolution
-```python
-# Before: Synchronous (blocks for 60+ seconds)
-POST /tenant/{id}/deploy → {status: "active", machine_id: "..."}
-
-# After: Asynchronous (returns immediately)
-POST /tenant/{id}/deploy → {job_id: "uuid", workflow_id: "uuid", status: "queued"}
-GET  /jobs/{job_id}/status → {status: "running", progress: "deploying_machine", workflow_id: "uuid"}
-GET  /workflows/{workflow_id}/events → [...] # Existing event tracking works unchanged
-```
-
-**Technology Choice**: **arq (Redis)** over pgqueuer
- **Existing Redis infrastructure** - Upstash + docker-compose already configured
- **Better ecosystem** - monitoring tools, documentation, community
- **Made by pydantic team** - aligns with existing Python stack
- **Hybrid approach** - Redis for queue operations + Postgres for workflow state
-
-#### Job Uniqueness Implementation
-
-**Problem**: Multiple concurrent deployment requests for the same tenant could create duplicate jobs, wasting resources and potentially causing conflicts.
-
-**Solution**: Leverage ARQ's built-in job uniqueness feature using predictable job IDs:
-
-```python
-# JobQueueService implementation
-async def enqueue_deploy_job(self, tenant_id: UUID, image_tag: str | None = None) -> str:
-    unique_job_id = f"deploy-{tenant_id}"
-
-    job = await self.redis_pool.enqueue_job(
-        "deploy_tenant_job",
-        str(tenant_id),
-        image_tag,
-        _job_id=unique_job_id,  # ARQ prevents duplicates
-    )
-
-    if job is None:
-        # Job already exists - return existing job ID
-        return unique_job_id
-    else:
-        # New job created - return ARQ job ID
-        return job.job_id
-```
-
-**Key Features:**
- **Predictable Job IDs**: `deploy-{tenant_id}`, `undeploy-{tenant_id}`
- **Duplicate Prevention**: ARQ returns `None` for duplicate job IDs
- **Graceful Handling**: Return existing job ID instead of raising errors
- **Idempotent Operations**: Safe to retry deployment requests
- **Clear Logging**: Distinguish "Enqueued new" vs "Found existing" jobs
-
-**Benefits:**
- Prevents resource waste from duplicate deployments
- Eliminates race conditions from concurrent requests
- Makes job monitoring more predictable with consistent IDs
- Provides natural deduplication without complex locking mechanisms
-
-
-## Notes
-
-### Design Philosophy Lessons
- **Simplicity beats framework magic** - removing DBOS made the system more reliable and debuggable
- **Event sourcing > complex orchestration** - database-backed event tracking provides better observability than framework abstractions
- **Idempotent operations > resumable workflows** - each step handling its own retry logic is simpler than framework-managed resumability
- **Explicit error handling > framework exception handling** - Python exceptions are clearer than orchestration framework error states
-
-### Future Considerations
- **Monitoring integration** - workflow tracking events could feed into observability systems
- **Performance optimization** - event querying patterns may benefit from additional indexing
- **Audit compliance** - complete event trail supports regulatory requirements
- **Operational dashboards** - workflow status could drive tenant health monitoring
-
-### Related Specifications
- **SPEC-8**: TigrisFS Integration - bucket provisioning integrated with deployment workflow
- **SPEC-1**: Specification-Driven Development Process - this spec follows the established format
-
-## Observations
-
- [architecture] Removing framework complexity led to more maintainable system #simplification
- [workflow] Single unified deployment workflow handles both provisioning and updates #consolidation
- [observability] Event sourcing with workflow correlation provides complete audit trail #event-tracking
- [database] Foreign key relationships between workflows and events enable powerful queries #schema-design
- [testing] Integration tests with real infrastructure catch edge cases that unit tests miss #testing-strategy
- [parameters] Consistent method signatures (workflow_id first) reduce cognitive overhead #api-design
- [maintenance] Fewer workflows and dependencies reduce long-term maintenance burden #operational-excellence
- [debugging] Plain Python exceptions are clearer than framework abstraction layers #developer-experience
- [resilience] Exponential backoff retry patterns handle flaky external API calls gracefully #error-handling
- [monitoring] Redis queue monitoring provides real-time operational visibility #observability
- [ci-cd] Bulk update commands enable automated tenant deployments in continuous delivery pipelines #automation
- [documentation] Comprehensive monitoring guides reduce operational learning curve #knowledge-management
- [error-logging] Context-aware log levels (INFO for expected errors, ERROR for unexpected) improve signal-to-noise ratio #logging-strategy
- [job-uniqueness] ARQ job uniqueness with predictable tenant-based IDs prevents duplicate operations and resource waste #deduplication
-
-## Implementation Notes
-
-### Configuration Integration
- **Redis Configuration**: Add Redis settings to existing `apps/cloud/src/basic_memory_cloud/config.py`
- **Local Development**: Leverage existing Redis setup from `docker-compose.yml`
- **Production**: Use Upstash Redis configuration for production environments
-
-### Docker Entrypoint Strategy
-Create `entrypoint.sh` script to toggle between API server and worker processes using single Docker image:
-
-```bash
-#!/bin/bash
-
-# Entrypoint script for Basic Memory Cloud service
-# Supports multiple process types: api, worker
-
-set -e
-
-case "$1" in
-  "api")
-    echo "Starting Basic Memory Cloud API server..."
-    exec uvicorn basic_memory_cloud.main:app \
-      --host 0.0.0.0 \
-      --port 8000 \
-      --log-level info
-    ;;
-  "worker")
-    echo "Starting Basic Memory Cloud ARQ worker..."
-    # For ARQ worker implementation
-    exec python -m arq basic_memory_cloud.jobs.settings.WorkerSettings
-    ;;
-  *)
-    echo "Usage: $0 {api|worker}"
-    echo "  api    - Start the FastAPI server"
-    echo "  worker - Start the ARQ worker"
-    exit 1
-    ;;
-esac
-```
-
-### Fly.io Process Groups Configuration
-Use separate machine groups for API and worker processes with independent scaling:
-
-```toml
-# fly.toml app configuration for basic-memory-cloud
-app = 'basic-memory-cloud-dev-basic-machines'
-primary_region = 'dfw'
-org = 'basic-machines'
-kill_signal = 'SIGINT'
-kill_timeout = '5s'
-
-[build]
-
-# Process groups for API server and worker
-[processes]
-  api = "api"
-  worker = "worker"
-
-# Machine scaling configuration
-[[machine]]
-  size = 'shared-cpu-1x'
-  processes = ['api']
-  min_machines_running = 1
-  auto_stop_machines = false
-  auto_start_machines = true
-
-[[machine]]
-  size = 'shared-cpu-1x'
-  processes = ['worker']
-  min_machines_running = 1
-  auto_stop_machines = false
-  auto_start_machines = true
-
-[env]
-  # Python configuration
-  PYTHONUNBUFFERED = '1'
-  PYTHONPATH = '/app'
-
-  # Logging configuration
-  LOG_LEVEL = 'DEBUG'
-
-  # Redis configuration for ARQ
-  REDIS_URL = 'redis://basic-memory-cloud-redis.upstash.io'
-
-  # Database configuration
-  DATABASE_HOST = 'basic-memory-cloud-db-dev-basic-machines.internal'
-  DATABASE_PORT = '5432'
-  DATABASE_NAME = 'basic_memory_cloud'
-  DATABASE_USER = 'postgres'
-  DATABASE_SSL = 'true'
-
-  # Worker configuration
-  ARQ_MAX_JOBS = '10'
-  ARQ_KEEP_RESULT = '3600'
-
-  # Fly.io configuration
-  FLY_ORG = 'basic-machines'
-  FLY_REGION = 'dfw'
-
-# Internal service - no external HTTP exposure for worker
-# API accessible via basic-memory-cloud-dev-basic-machines.flycast:8000
-
-[[vm]]
-  size = 'shared-cpu-1x'
-```
-
-### Benefits of This Architecture
- **Single Docker Image**: Both API and worker use same container with different entrypoints
- **Independent Scaling**: Scale API and worker processes separately based on demand
- **Clean Separation**: Web traffic handling separate from background job processing
- **Existing Infrastructure**: Leverages current PostgreSQL + Redis setup without complexity
- **Hybrid State Management**: Redis for queue operations, PostgreSQL for persistent workflow tracking
-
-## Relations
-
- implements [[SPEC-8 TigrisFS Integration]]
- follows [[SPEC-1 Specification-Driven Development Process]]
- supersedes previous multi-workflow architecture
@@ -1,186 +0,0 @@
---
-title: 'SPEC-11: Basic Memory API Performance Optimization'
-type: spec
-permalink: specs/spec-11-basic-memory-api-performance-optimization
-tags:
- performance
- api
- mcp
- database
- cloud
---
-
-# SPEC-11: Basic Memory API Performance Optimization
-
-## Why
-
-The Basic Memory API experiences significant performance issues in cloud environments due to expensive per-request initialization. MCP tools making
-HTTP requests to the API suffer from 350ms-2.6s latency overhead **before** any actual operation occurs.
-
-**Root Cause Analysis:**
- GitHub Issue #82 shows repeated initialization sequences in logs (16:29:35 and 16:49:58)
- Each MCP tool call triggers full database initialization + project reconciliation
- `get_engine_factory()` dependency calls `db.get_or_create_db()` on every request
- `reconcile_projects_with_config()` runs expensive sync operations repeatedly
-
-**Performance Impact:**
- Database connection setup: ~50-100ms per request
- Migration checks: ~100-500ms per request
- Project reconciliation: ~200ms-2s per request
- **Total overhead**: ~350ms-2.6s per MCP tool call
-
-This creates compounding effects with tenant auto-start delays and increases timeout risk in cloud deployments.
-
-## What
-
-This optimization affects the **core basic-memory repository** components:
-
-1. **API Lifespan Management** (`src/basic_memory/api/app.py`)
- - Cache database connections in app state during startup
- - Avoid repeated expensive initialization
-
-2. **Dependency Injection** (`src/basic_memory/deps.py`)
- - Modify `get_engine_factory()` to use cached connections
- - Eliminate per-request database setup
-
-3. **Initialization Service** (`src/basic_memory/services/initialization.py`)
- - Add caching/throttling to project reconciliation
- - Skip expensive operations when appropriate
-
-4. **Configuration** (`src/basic_memory/config.py`)
- - Add optional performance flags for cloud environments
-
-**Backwards Compatibility**: All changes must be backwards compatible with existing CLI and non-cloud usage.
-
-## How (High Level)
-
-### Phase 1: Cache Database Connections (Critical - 80% of gains)
-
-**Problem**: `get_engine_factory()` calls `db.get_or_create_db()` per request
-**Solution**: Cache database engine/session in app state during lifespan
-
-1. **Modify API Lifespan** (`api/app.py`):
- ```python
- @asynccontextmanager
- async def lifespan(app: FastAPI):
-     app_config = ConfigManager().config
-     await initialize_app(app_config)
-
-     # Cache database connection in app state
-     engine, session_maker = await db.get_or_create_db(app_config.database_path)
-     app.state.engine = engine
-     app.state.session_maker = session_maker
-
-     # ... rest of startup logic
-```
-
-2. Modify Dependency Injection (deps.py):
-```python
-async def get_engine_factory(
-  request: Request
-) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
-  """Get cached engine and session maker from app state."""
-  return request.app.state.engine, request.app.state.session_maker
-```
-Phase 2: Optimize Project Reconciliation (Secondary - 20% of gains)
-
-Problem: reconcile_projects_with_config() runs expensive sync repeatedly
-Solution: Add module-level caching with time-based throttling
-
-1. Add Reconciliation Cache (services/initialization.py):
-```ptyhon
-_project_reconciliation_completed = False
-_last_reconciliation_time = 0
-
-async def reconcile_projects_with_config(app_config, force=False):
-  # Skip if recently completed (within 60 seconds) unless forced
-  if recently_completed and not force:
-      return
-  # ... existing logic
-```
-Phase 3: Cloud Environment Flags (Optional)
-
-Problem: Force expensive initialization in production environments
-Solution: Add skip flags for cloud/stateless deployments
-
-1. Add Config Flag (config.py):
-skip_initialization_sync: bool = Field(default=False)
-2. Configure in Cloud (basic-memory-cloud integration):
-BASIC_MEMORY_SKIP_INITIALIZATION_SYNC=true
-
-How to Evaluate
-
-Success Criteria
-
-1. Performance Metrics (Primary):
- MCP tool response time reduced by 50%+ (measure before/after)
- Database connection overhead eliminated (0ms vs 50-100ms)
- Migration check overhead eliminated (0ms vs 100-500ms)
- Project reconciliation overhead reduced by 90%+
-2. Load Testing:
- Concurrent MCP tool calls maintain performance
- No memory leaks in cached connections
- Database connection pool behaves correctly
-3. Functional Correctness:
- All existing API endpoints work identically
- MCP tools maintain full functionality
- CLI operations unaffected
- Database migrations still execute properly
-4. Backwards Compatibility:
- No breaking changes to existing APIs
- Config changes are optional with safe defaults
- Non-cloud deployments work unchanged
-
-Testing Strategy
-
-Performance Testing:
-# Before optimization
-time basic-memory-mcp-tools write_note "test" "content" "folder"
-# Measure: ~1-3 seconds
-
-# After optimization  
-time basic-memory-mcp-tools write_note "test" "content" "folder"
-# Target: <500ms
-
-Load Testing:
-# Multiple concurrent MCP tool calls
-for i in {1..10}; do
-basic-memory-mcp-tools search "test" &
-done
-wait
-# Verify: No degradation, consistent response times
-
-Regression Testing:
-# Full basic-memory test suite
-just test
-# All tests must pass
-
-# Integration tests with cloud deployment
-# Verify MCP gateway → API → database flow works
-
-Validation Checklist
-
- Phase 1 Complete: Database connections cached, dependency injection optimized
- Performance Benchmark: 50%+ improvement in MCP tool response times
- Memory Usage: No leaks in cached connections over 24h+ periods
- Stress Testing: 100+ concurrent requests maintain performance
- Backwards Compatibility: All existing functionality preserved
- Documentation: Performance optimization documented in README
- Cloud Integration: basic-memory-cloud sees performance benefits
-
-Notes
-
-Implementation Priority:
- Phase 1 provides 80% of performance gains and should be implemented first
- Phase 2 provides remaining 20% and addresses edge cases
- Phase 3 is optional for maximum cloud optimization
-
-Risk Mitigation:
- All changes backwards compatible
- Gradual rollout possible (Phase 1 → 2 → 3)
- Easy rollback via configuration flags
-
-Cloud Integration:
- This optimization directly addresses basic-memory-cloud issue #82
- Changes in core basic-memory will benefit all cloud tenants
- No changes needed in basic-memory-cloud itself
@@ -1,182 +0,0 @@
-# SPEC-12: OpenTelemetry Observability
-
-## Why
-
-We need comprehensive observability for basic-memory-cloud to:
- Track request flows across our multi-tenant architecture (MCP → Cloud → API services)
- Debug performance issues and errors in production
- Understand user behavior and system usage patterns
- Correlate issues to specific tenants for targeted debugging
- Monitor service health and latency across the distributed system
-
-Currently, we only have basic logging without request correlation or distributed tracing capabilities.
-
-## What
-
-Implement OpenTelemetry instrumentation across all basic-memory-cloud services with:
-
-### Core Requirements
-1. **Distributed Tracing**: End-to-end request tracing from MCP gateway through to tenant API instances
-2. **Tenant Correlation**: All traces tagged with tenant_id, user_id, and workos_user_id
-3. **Service Identification**: Clear service naming and namespace separation
-4. **Auto-instrumentation**: Automatic tracing for FastAPI, SQLAlchemy, HTTP clients
-5. **Grafana Cloud Integration**: Direct OTLP export to Grafana Cloud Tempo
-
-### Services to Instrument
- **MCP Gateway** (basic-memory-mcp): Entry point with JWT extraction
- **Cloud Service** (basic-memory-cloud): Provisioning and management operations
- **API Service** (basic-memory-api): Tenant-specific instances
- **Worker Processes** (ARQ workers): Background job processing
-
-### Key Trace Attributes
- `tenant.id`: UUID from UserProfile.tenant_id
- `user.id`: WorkOS user identifier
- `user.email`: User email for debugging
- `service.name`: Specific service identifier
- `service.namespace`: Environment (development/production)
- `operation.type`: Business operation (provision/update/delete)
- `tenant.app_name`: Fly.io app name for tenant instances
-
-## How
-
-### Phase 1: Setup OpenTelemetry SDK
-1. Add OpenTelemetry dependencies to each service's pyproject.toml:
-   ```python
-   "opentelemetry-distro[otlp]>=1.29.0",
-   "opentelemetry-instrumentation-fastapi>=0.50b0",
-   "opentelemetry-instrumentation-httpx>=0.50b0",
-   "opentelemetry-instrumentation-sqlalchemy>=0.50b0",
-   "opentelemetry-instrumentation-logging>=0.50b0",
-   ```
-
-2. Create shared telemetry initialization module (`apps/shared/telemetry.py`)
-
-3. Configure Grafana Cloud OTLP endpoint via environment variables:
-   ```bash
-   OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-us-east-2.grafana.net/otlp
-   OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic[token]
-   OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
-   ```
-
-### Phase 2: Instrument MCP Gateway
-1. Extract tenant context from AuthKit JWT in middleware
-2. Create root span with tenant attributes
-3. Propagate trace context to downstream services via headers
-
-### Phase 3: Instrument Cloud Service
-1. Continue trace from MCP gateway
-2. Add operation-specific attributes (provisioning events)
-3. Instrument ARQ worker jobs for async operations
-4. Track Fly.io API calls and latency
-
-### Phase 4: Instrument API Service
-1. Extract tenant context from JWT
-2. Add machine-specific metadata (instance ID, region)
-3. Instrument database operations with SQLAlchemy
-4. Track MCP protocol operations
-
-### Phase 5: Configure and Deploy
-1. Add OTLP configuration to `.env.example` and `.env.example.secrets`
-2. Set Fly.io secrets for production deployment
-3. Update Dockerfiles to use `opentelemetry-instrument` wrapper
-4. Deploy to development environment first for testing
-
-## How to Evaluate
-
-### Success Criteria
-1. **End-to-end traces visible in Grafana Cloud** showing complete request flow
-2. **Tenant filtering works** - Can filter traces by tenant_id to see all requests for a user
-3. **Service maps accurate** - Grafana shows correct service dependencies
-4. **Performance overhead < 5%** - Minimal latency impact from instrumentation
-5. **Error correlation** - Can trace errors back to specific tenant and operation
-
-### Testing Checklist
- [x] Single request creates connected trace across all services
- [x] Tenant attributes present on all spans
- [x] Background jobs (ARQ) appear in traces
- [x] Database queries show in trace timeline
- [x] HTTP calls to Fly.io API tracked
- [x] Traces exported successfully to Grafana Cloud
- [x] Can search traces by tenant_id in Grafana
- [x] Service dependency graph shows correct flow
-
-### Monitoring Success
- All services reporting traces to Grafana Cloud
- No OTLP export errors in logs
- Trace sampling working correctly (if implemented)
- Resource usage acceptable (CPU/memory)
-
-## Dependencies
- Grafana Cloud account with OTLP endpoint configured
- OpenTelemetry Python SDK v1.29.0+
- FastAPI instrumentation compatibility
- Network access from Fly.io to Grafana Cloud
-
-## Implementation Assignment
-**Recommended Agent**: python-developer
- Requires Python/FastAPI expertise
- Needs understanding of distributed systems
- Must implement middleware and context propagation
- Should understand OpenTelemetry SDK and instrumentation
-
-## Follow-up Tasks
-
-### Enhanced Log Correlation
-While basic trace-to-log correlation works automatically via OpenTelemetry logging instrumentation, consider adding structured logging for improved log filtering:
-
-1. **Structured Logging Context**: Add `logger.bind()` calls to inject tenant/user context directly into log records
-2. **Custom Loguru Formatter**: Extract OpenTelemetry span attributes for better log readability
-3. **Direct Log Filtering**: Enable searching logs directly by tenant_id, workflow_id without going through traces
-
-This would complement the existing automatic trace correlation and provide better log search capabilities.
-
-## Alternative Solution: Logfire
-
-After implementing OpenTelemetry with Grafana Cloud, we discovered limitations in the observability experience:
- Traces work but lack useful context without correlated logs
- Setting up log correlation with Grafana is complex and requires additional infrastructure
- The developer experience for Python observability is suboptimal
-
-### Logfire Evaluation
-
-**Pydantic Logfire** offers a compelling alternative that addresses your specific requirements:
-
-#### Core Requirements Match
- ✅ **User Activity Tracking**: Automatic request tracing with business context
- ✅ **Error Monitoring**: Built-in exception tracking with full context
- ✅ **Performance Metrics**: Automatic latency and performance monitoring
- ✅ **Request Tracing**: Native distributed tracing across services
- ✅ **Log Correlation**: Seamless trace-to-log correlation without setup
-
-#### Key Advantages
-1. **Python-First Design**: Built specifically for Python/FastAPI applications by the Pydantic team
-2. **Simple Integration**: `pip install logfire` + `logfire.configure()` vs complex OTLP setup
-3. **Automatic Correlation**: Logs automatically include trace context without manual configuration
-4. **Real-time SQL Interface**: Query spans and logs using SQL with auto-completion
-5. **Better Developer UX**: Purpose-built observability UI vs generic Grafana dashboards
-6. **Loguru Integration**: `logger.configure(handlers=[logfire.loguru_handler()])` maintains existing logging
-
-#### Pricing Assessment
- **Free Tier**: 10M spans/month (suitable for development and small production workloads)
- **Transparent Pricing**: $1 per million spans/metrics after free tier
- **No Hidden Costs**: No per-host fees, only usage-based metering
- **Production Ready**: Recently exited beta, enterprise features available
-
-#### Migration Path
-The existing OpenTelemetry instrumentation is compatible - Logfire uses OpenTelemetry under the hood, so the current spans and attributes would work unchanged.
-
-### Recommendation
-
-**Consider migrating to Logfire** for the following reasons:
-1. It directly addresses the "next to useless" traces problem by providing integrated logs
-2. Dramatically simpler setup and maintenance compared to Grafana Cloud + custom log correlation
-3. Better ROI on observability investment with purpose-built Python tooling
-4. Free tier sufficient for current development needs with clear scaling path
-
-The current Grafana Cloud implementation provides a solid foundation and could remain as a backup/export target, while Logfire becomes the primary observability platform.
-
-## Status
-**Created**: 2024-01-28
-**Status**: Completed (OpenTelemetry + Grafana Cloud)
-**Next Phase**: Evaluate Logfire migration
-**Priority**: High - Critical for production observability
@@ -1,917 +0,0 @@
---
-title: 'SPEC-13: CLI Authentication with Subscription Validation'
-type: spec
-permalink: specs/spec-12-cli-auth-subscription-validation
-tags:
- authentication
- security
- cli
- subscription
-status: draft
-created: 2025-10-02
---
-
-# SPEC-13: CLI Authentication with Subscription Validation
-
-## Why
-
-The Basic Memory Cloud CLI currently has a security gap in authentication that allows unauthorized access:
-
-**Current Web Flow (Secure)**:
-1. User signs up via WorkOS AuthKit
-2. User creates Polar subscription
-3. Web app validates subscription before calling `POST /tenants/setup`
-4. Tenant provisioned only after subscription validation ✅
-
-**Current CLI Flow (Insecure)**:
-1. User signs up via WorkOS AuthKit (OAuth device flow)
-2. User runs `bm cloud login`
-3. CLI receives JWT token from WorkOS
-4. CLI can access all cloud endpoints without subscription check ❌
-
-**Problem**: Anyone can sign up with WorkOS and immediately access cloud infrastructure via CLI without having an active Polar subscription. This creates:
- Revenue loss (free resource consumption)
- Security risk (unauthorized data access)
- Support burden (users accessing features they haven't paid for)
-
-**Root Cause**: The CLI authentication flow validates JWT tokens but doesn't verify subscription status before granting access to cloud resources.
-
-## What
-
-Add subscription validation to authentication flow to ensure only users with active Polar subscriptions can access cloud resources across all access methods (CLI, MCP, Web App, Direct API).
-
-**Affected Components**:
-
-### basic-memory-cloud (Cloud Service)
- `apps/cloud/src/basic_memory_cloud/deps.py` - Add subscription validation dependency
- `apps/cloud/src/basic_memory_cloud/services/subscription_service.py` - Add subscription check method
- `apps/cloud/src/basic_memory_cloud/api/tenant_mount.py` - Protect mount endpoints
- `apps/cloud/src/basic_memory_cloud/api/proxy.py` - Protect proxy endpoints
-
-### basic-memory (CLI)
- `src/basic_memory/cli/commands/cloud/core_commands.py` - Handle 403 errors
- `src/basic_memory/cli/commands/cloud/api_client.py` - Parse subscription errors
- `docs/cloud-cli.md` - Document subscription requirement
-
-**Endpoints to Protect**:
- `GET /tenant/mount/info` - Used by CLI bisync setup
- `POST /tenant/mount/credentials` - Used by CLI bisync credentials
- `GET /proxy/{path:path}` - Used by Web App, MCP tools, CLI tools, Direct API
- All other `/proxy/*` endpoints - Centralized access point for all user operations
-
-## Complete Authentication Flow Analysis
-
-### Overview of All Access Flows
-
-Basic Memory Cloud has **7 distinct authentication flows**. This spec closes subscription validation gaps in flows 2-4 and 6, which all converge on the `/proxy/*` endpoints.
-
-### Flow 1: Polar Webhook → Registration ✅ SECURE
-```
-Polar webhook → POST /api/webhooks/polar
-→ Validates Polar webhook signature
-→ Creates/updates subscription in database
-→ No direct user access - webhook only
-```
-**Auth**: Polar webhook signature validation
-**Subscription Check**: N/A (webhook creates subscriptions)
-**Status**: ✅ Secure - webhook validated, no user JWT involved
-
-### Flow 2: Web App Login ❌ NEEDS FIX
-```
-User → apps/web (Vue.js/Nuxt)
-→ WorkOS AuthKit magic link authentication
-→ JWT stored in browser session
-→ Web app calls /proxy/{project}/... endpoints (memory, directory, projects)
-→ proxy.py validates JWT but does NOT check subscription
-→ Access granted without subscription ❌
-```
-**Auth**: WorkOS JWT via `CurrentUserProfileHybridJwtDep`
-**Subscription Check**: ❌ Missing
-**Fixed By**: Task 1.4 (protect `/proxy/*` endpoints)
-
-### Flow 3: MCP (Model Context Protocol) ❌ NEEDS FIX
-```
-AI Agent (Claude, Cursor, etc.) → https://mcp.basicmemory.com
-→ AuthKit OAuth device flow
-→ JWT stored in AI agent
-→ MCP tools call {cloud_host}/proxy/{endpoint} with Authorization header
-→ proxy.py validates JWT but does NOT check subscription
-→ MCP tools can access all cloud resources without subscription ❌
-```
-**Auth**: AuthKit JWT via `CurrentUserProfileHybridJwtDep`
-**Subscription Check**: ❌ Missing
-**Fixed By**: Task 1.4 (protect `/proxy/*` endpoints)
-
-### Flow 4: CLI Auth (basic-memory) ❌ NEEDS FIX
-```
-User → bm cloud login
-→ AuthKit OAuth device flow
-→ JWT stored in ~/.basic-memory/tokens.json
-→ CLI calls:
-  - {cloud_host}/tenant/mount/info (for bisync setup)
-  - {cloud_host}/tenant/mount/credentials (for bisync credentials)
-  - {cloud_host}/proxy/{endpoint} (for all MCP tools)
-→ tenant_mount.py and proxy.py validate JWT but do NOT check subscription
-→ Access granted without subscription ❌
-```
-**Auth**: AuthKit JWT via `CurrentUserProfileHybridJwtDep`
-**Subscription Check**: ❌ Missing
-**Fixed By**: Task 1.3 (protect `/tenant/mount/*`) + Task 1.4 (protect `/proxy/*`)
-
-### Flow 5: Cloud CLI (Admin Tasks) ✅ SECURE
-```
-Admin → python -m basic_memory_cloud.cli.tenant_cli
-→ Uses CLIAuth with admin WorkOS OAuth client
-→ Gets JWT token with admin org membership
-→ Calls /tenants/* endpoints (create, list, delete tenants)
-→ tenants.py validates JWT AND admin org membership via AdminUserHybridDep
-→ Access granted only to admin organization members ✅
-```
-**Auth**: AuthKit JWT + Admin org validation via `AdminUserHybridDep`
-**Subscription Check**: N/A (admins bypass subscription requirement)
-**Status**: ✅ Secure - admin-only endpoints, separate from user flows
-
-### Flow 6: Direct API Calls ❌ NEEDS FIX
-```
-Any HTTP client → {cloud_host}/proxy/{endpoint}
-→ Sends Authorization: Bearer {jwt} header
-→ proxy.py validates JWT but does NOT check subscription
-→ Direct API access without subscription ❌
-```
-**Auth**: WorkOS or AuthKit JWT via `CurrentUserProfileHybridJwtDep`
-**Subscription Check**: ❌ Missing
-**Fixed By**: Task 1.4 (protect `/proxy/*` endpoints)
-
-### Flow 7: Tenant API Instance (Internal) ✅ SECURE
-```
-/proxy/* → Tenant API (basic-memory-{tenant_id}.fly.dev)
-→ Validates signed header from proxy (tenant_id + signature)
-→ Direct external access will be disabled in production
-→ Only accessible via /proxy endpoints
-```
-**Auth**: Signed header validation from proxy
-**Subscription Check**: N/A (internal only, validated at proxy layer)
-**Status**: ✅ Secure - validates proxy signature, not directly accessible
-
-### Authentication Flow Summary Matrix
-
-| Flow | Access Method | Current Auth | Subscription Check | Fixed By SPEC-13 |
-|------|---------------|--------------|-------------------|------------------|
-| 1. Polar Webhook | Polar webhook → `/api/webhooks/polar` | Polar signature | N/A (webhook) | N/A |
-| 2. Web App | Browser → `/proxy/*` | WorkOS JWT ✅ | ❌ Missing | ✅ Task 1.4 |
-| 3. MCP | AI Agent → `/proxy/*` | AuthKit JWT ✅ | ❌ Missing | ✅ Task 1.4 |
-| 4. CLI | `bm cloud` → `/tenant/mount/*` + `/proxy/*` | AuthKit JWT ✅ | ❌ Missing | ✅ Task 1.3 + 1.4 |
-| 5. Cloud CLI (Admin) | `tenant_cli` → `/tenants/*` | AuthKit JWT ✅ + Admin org | N/A (admin) | N/A (admin bypass) |
-| 6. Direct API | HTTP client → `/proxy/*` | WorkOS/AuthKit JWT ✅ | ❌ Missing | ✅ Task 1.4 |
-| 7. Tenant API | Proxy → tenant instance | Proxy signature ✅ | N/A (internal) | N/A |
-
-### Key Insights
-
-1. **Single Point of Failure**: All user access (Web, MCP, CLI, Direct API) converges on `/proxy/*` endpoints
-2. **Centralized Fix**: Protecting `/proxy/*` with subscription validation closes gaps in flows 2, 3, 4, and 6 simultaneously
-3. **Admin Bypass**: Cloud CLI admin tasks use separate `/tenants/*` endpoints with admin-only access (no subscription needed)
-4. **Defense in Depth**: `/tenant/mount/*` endpoints also protected for CLI bisync operations
-
-### Architecture Benefits
-
-The `/proxy` layer serves as the **single centralized authorization point** for all user access:
- ✅ One place to validate JWT tokens
- ✅ One place to check subscription status
- ✅ One place to handle tenant routing
- ✅ Protects Web App, MCP, CLI, and Direct API simultaneously
-
-This architecture makes the fix comprehensive and maintainable.
-
-## How (High Level)
-
-### Option A: Database Subscription Check (Recommended)
-
-**Approach**: Add FastAPI dependency that validates subscription status from database before allowing access.
-
-**Implementation**:
-
-1. **Create Subscription Validation Dependency** (`deps.py`)
-   ```python
-   async def get_authorized_cli_user_profile(
-       credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)],
-       session: DatabaseSessionDep,
-       user_profile_repo: UserProfileRepositoryDep,
-       subscription_service: SubscriptionServiceDep,
-   ) -> UserProfile:
-       """
-       Hybrid authentication with subscription validation for CLI access.
-
-       Validates JWT (WorkOS or AuthKit) and checks for active subscription.
-       Returns UserProfile if both checks pass.
-       """
-       # Try WorkOS JWT first (faster validation path)
-       try:
-           user_context = await validate_workos_jwt(credentials.credentials)
-       except HTTPException:
-           # Fall back to AuthKit JWT validation
-           try:
-               user_context = await validate_authkit_jwt(credentials.credentials)
-           except HTTPException as e:
-               raise HTTPException(
-                   status_code=401,
-                   detail="Invalid JWT token. Authentication required.",
-               ) from e
-
-       # Check subscription status
-       has_subscription = await subscription_service.check_user_has_active_subscription(
-           session, user_context.workos_user_id
-       )
-
-       if not has_subscription:
-           raise HTTPException(
-               status_code=403,
-               detail={
-                   "error": "subscription_required",
-                   "message": "Active subscription required for CLI access",
-                   "subscribe_url": "https://basicmemory.com/subscribe"
-               }
-           )
-
-       # Look up and return user profile
-       user_profile = await user_profile_repo.get_user_profile_by_workos_user_id(
-           session, user_context.workos_user_id
-       )
-       if not user_profile:
-           raise HTTPException(401, detail="User profile not found")
-
-       return user_profile
-   ```
-
-   ```python
-   AuthorizedCLIUserProfileDep = Annotated[UserProfile, Depends(get_authorized_cli_user_profile)]
-   ```
-
-2. **Add Subscription Check Method** (`subscription_service.py`)
-   ```python
-   async def check_user_has_active_subscription(
-       self, session: AsyncSession, workos_user_id: str
-   ) -> bool:
-       """Check if user has active subscription."""
-       # Use existing repository method to get subscription by workos_user_id
-       # This joins UserProfile -> Subscription in a single query
-       subscription = await self.subscription_repository.get_subscription_by_workos_user_id(
-           session, workos_user_id
-       )
-
-       return subscription is not None and subscription.status == "active"
-   ```
-
-3. **Protect Endpoints** (Replace `CurrentUserProfileHybridJwtDep` with `AuthorizedCLIUserProfileDep`)
-   ```python
-   # Before
-   @router.get("/mount/info")
-   async def get_mount_info(
-       user_profile: CurrentUserProfileHybridJwtDep,
-       session: DatabaseSessionDep,
-   ):
-       tenant_id = user_profile.tenant_id
-       ...
-
-   # After
-   @router.get("/mount/info")
-   async def get_mount_info(
-       user_profile: AuthorizedCLIUserProfileDep,  # Now includes subscription check
-       session: DatabaseSessionDep,
-   ):
-       tenant_id = user_profile.tenant_id  # No changes needed to endpoint logic
-       ...
-   ```
-
-4. **Update CLI Error Handling**
-   ```python
-   # In core_commands.py login()
-   try:
-       success = await auth.login()
-       if success:
-           # Test subscription by calling protected endpoint
-           await make_api_request("GET", f"{host_url}/tenant/mount/info")
-   except CloudAPIError as e:
-       if e.status_code == 403 and e.detail.get("error") == "subscription_required":
-           console.print("[red]Subscription required[/red]")
-           console.print(f"Subscribe at: {e.detail['subscribe_url']}")
-           raise typer.Exit(1)
-   ```
-
-**Pros**:
- Simple to implement
- Fast (single database query)
- Clear error messages
- Works with existing subscription flow
-
-**Cons**:
- Database is source of truth (could get out of sync with Polar)
- Adds one extra subscription lookup query per request (lightweight JOIN query)
-
-### Option B: WorkOS Organizations
-
-**Approach**: Add users to "beta-users" organization in WorkOS after subscription creation, validate org membership via JWT claims.
-
-**Implementation**:
-1. After Polar subscription webhook, add user to WorkOS org via API
-2. Validate `org_id` claim in JWT matches authorized org
-3. Use existing `get_admin_workos_jwt` pattern
-
-**Pros**:
- WorkOS as single source of truth
- No database queries needed
- More secure (harder to bypass)
-
-**Cons**:
- More complex (requires WorkOS API integration)
- Requires managing WorkOS org membership
- Less control over error messages
- Additional API calls during registration
-
-### Recommendation
-
-**Start with Option A (Database Check)** for:
- Faster implementation
- Clearer error messages
- Easier testing
- Existing subscription infrastructure
-
-**Consider Option B later** if:
- Need tighter security
- Want to reduce database dependency
- Scale requires fewer database queries
-
-## How to Evaluate
-
-### Success Criteria
-
-**1. Unauthorized Users Blocked**
- [ ] User without subscription cannot complete `bm cloud login`
- [ ] User without subscription receives clear error with subscribe link
- [ ] User without subscription cannot run `bm cloud setup`
- [ ] User without subscription cannot run `bm sync` in cloud mode
-
-**2. Authorized Users Work**
- [ ] User with active subscription can login successfully
- [ ] User with active subscription can setup bisync
- [ ] User with active subscription can sync files
- [ ] User with active subscription can use all MCP tools via proxy
-
-**3. Subscription State Changes**
- [ ] Expired subscription blocks access with clear error
- [ ] Renewed subscription immediately restores access
- [ ] Cancelled subscription blocks access after grace period
-
-**4. Error Messages**
- [ ] 403 errors include "subscription_required" error code
- [ ] Error messages include subscribe URL
- [ ] CLI displays user-friendly messages
- [ ] Errors logged appropriately for debugging
-
-**5. No Regressions**
- [ ] Web app login/subscription flow unaffected
- [ ] Admin endpoints still work (bypass check)
- [ ] Tenant provisioning workflow unchanged
- [ ] Performance not degraded
-
-### Test Cases
-
-**Manual Testing**:
-```bash
-# Test 1: Unauthorized user
-1. Create new WorkOS account (no subscription)
-2. Run `bm cloud login`
-3. Verify: Login succeeds but shows subscription required error
-4. Verify: Cannot run `bm cloud setup`
-5. Verify: Clear error message with subscribe link
-
-# Test 2: Authorized user
-1. Use account with active Polar subscription
-2. Run `bm cloud login`
-3. Verify: Login succeeds without errors
-4. Run `bm cloud setup`
-5. Verify: Setup completes successfully
-6. Run `bm sync`
-7. Verify: Sync works normally
-
-# Test 3: Subscription expiration
-1. Use account with active subscription
-2. Manually expire subscription in database
-3. Run `bm cloud login`
-4. Verify: Blocked with clear error
-5. Renew subscription
-6. Run `bm cloud login` again
-7. Verify: Access restored
-```
-
-**Automated Tests**:
-```python
-# Test subscription validation dependency
-async def test_authorized_user_allowed(
-    db_session,
-    user_profile_repo,
-    subscription_service,
-    mock_jwt_credentials
-):
-    # Create user with active subscription
-    user_profile = await create_user_with_subscription(db_session, status="active")
-
-    # Mock JWT credentials for the user
-    credentials = mock_jwt_credentials(user_profile.workos_user_id)
-
-    # Should not raise exception
-    result = await get_authorized_cli_user_profile(
-        credentials, db_session, user_profile_repo, subscription_service
-    )
-    assert result.id == user_profile.id
-    assert result.workos_user_id == user_profile.workos_user_id
-
-async def test_unauthorized_user_blocked(
-    db_session,
-    user_profile_repo,
-    subscription_service,
-    mock_jwt_credentials
-):
-    # Create user without subscription
-    user_profile = await create_user_without_subscription(db_session)
-    credentials = mock_jwt_credentials(user_profile.workos_user_id)
-
-    # Should raise 403
-    with pytest.raises(HTTPException) as exc:
-        await get_authorized_cli_user_profile(
-            credentials, db_session, user_profile_repo, subscription_service
-        )
-
-    assert exc.value.status_code == 403
-    assert exc.value.detail["error"] == "subscription_required"
-
-async def test_inactive_subscription_blocked(
-    db_session,
-    user_profile_repo,
-    subscription_service,
-    mock_jwt_credentials
-):
-    # Create user with cancelled/inactive subscription
-    user_profile = await create_user_with_subscription(db_session, status="cancelled")
-    credentials = mock_jwt_credentials(user_profile.workos_user_id)
-
-    # Should raise 403
-    with pytest.raises(HTTPException) as exc:
-        await get_authorized_cli_user_profile(
-            credentials, db_session, user_profile_repo, subscription_service
-        )
-
-    assert exc.value.status_code == 403
-    assert exc.value.detail["error"] == "subscription_required"
-```
-
-## Implementation Tasks
-
-### Phase 1: Cloud Service (basic-memory-cloud)
-
-#### Task 1.1: Add subscription check method to SubscriptionService ✅
-**File**: `apps/cloud/src/basic_memory_cloud/services/subscription_service.py`
-
- [x] Add method `check_subscription(session: AsyncSession, workos_user_id: str) -> bool`
- [x] Use existing `self.subscription_repository.get_subscription_by_workos_user_id(session, workos_user_id)`
- [x] Check both `status == "active"` AND `current_period_end >= now()`
- [x] Log both values when check fails
- [x] Add docstring explaining the method
- [x] Run `just typecheck` to verify types
-
-**Actual implementation**:
-```python
-async def check_subscription(
-    self, session: AsyncSession, workos_user_id: str
-) -> bool:
-    """Check if user has active subscription with valid period."""
-    subscription = await self.subscription_repository.get_subscription_by_workos_user_id(
-        session, workos_user_id
-    )
-
-    if subscription is None:
-        return False
-
-    if subscription.status != "active":
-        logger.warning("Subscription inactive", workos_user_id=workos_user_id,
-                      status=subscription.status, current_period_end=subscription.current_period_end)
-        return False
-
-    now = datetime.now(timezone.utc)
-    if subscription.current_period_end is None or subscription.current_period_end < now:
-        logger.warning("Subscription expired", workos_user_id=workos_user_id,
-                      status=subscription.status, current_period_end=subscription.current_period_end)
-        return False
-
-    return True
-```
-
-#### Task 1.2: Add subscription validation dependency ✅
-**File**: `apps/cloud/src/basic_memory_cloud/deps.py`
-
- [x] Import necessary types at top of file (if not already present)
- [x] Add `authorized_user_profile()` async function
- [x] Implement hybrid JWT validation (WorkOS first, AuthKit fallback)
- [x] Add subscription check using `subscription_service.check_subscription()`
- [x] Raise `HTTPException(403)` with structured error detail if no active subscription
- [x] Look up and return `UserProfile` after validation
- [x] Add `AuthorizedUserProfileDep` type annotation
- [x] Use `settings.subscription_url` from config (env var)
- [x] Run `just typecheck` to verify types
-
-**Expected code**:
-```python
-async def get_authorized_cli_user_profile(
-    credentials: Annotated[HTTPAuthorizationCredentials, Depends(security)],
-    session: DatabaseSessionDep,
-    user_profile_repo: UserProfileRepositoryDep,
-    subscription_service: SubscriptionServiceDep,
-) -> UserProfile:
-    """
-    Hybrid authentication with subscription validation for CLI access.
-
-    Validates JWT (WorkOS or AuthKit) and checks for active subscription.
-    Returns UserProfile if both checks pass.
-
-    Raises:
-        HTTPException(401): Invalid JWT token
-        HTTPException(403): No active subscription
-    """
-    # Try WorkOS JWT first (faster validation path)
-    try:
-        user_context = await validate_workos_jwt(credentials.credentials)
-    except HTTPException:
-        # Fall back to AuthKit JWT validation
-        try:
-            user_context = await validate_authkit_jwt(credentials.credentials)
-        except HTTPException as e:
-            raise HTTPException(
-                status_code=401,
-                detail="Invalid JWT token. Authentication required.",
-            ) from e
-
-    # Check subscription status
-    has_subscription = await subscription_service.check_user_has_active_subscription(
-        session, user_context.workos_user_id
-    )
-
-    if not has_subscription:
-        logger.warning(
-            "CLI access denied: no active subscription",
-            workos_user_id=user_context.workos_user_id,
-        )
-        raise HTTPException(
-            status_code=403,
-            detail={
-                "error": "subscription_required",
-                "message": "Active subscription required for CLI access",
-                "subscribe_url": "https://basicmemory.com/subscribe"
-            }
-        )
-
-    # Look up and return user profile
-    user_profile = await user_profile_repo.get_user_profile_by_workos_user_id(
-        session, user_context.workos_user_id
-    )
-    if not user_profile:
-        logger.error(
-            "User profile not found after successful auth",
-            workos_user_id=user_context.workos_user_id,
-        )
-        raise HTTPException(401, detail="User profile not found")
-
-    logger.info(
-        "CLI access granted",
-        workos_user_id=user_context.workos_user_id,
-        user_profile_id=str(user_profile.id),
-    )
-    return user_profile
-
-
-AuthorizedCLIUserProfileDep = Annotated[UserProfile, Depends(get_authorized_cli_user_profile)]
-```
-
-#### Task 1.3: Protect tenant mount endpoints ✅
-**File**: `apps/cloud/src/basic_memory_cloud/api/tenant_mount.py`
-
- [x] Update import: add `AuthorizedUserProfileDep` from `..deps`
- [x] Replace `user_profile: CurrentUserProfileHybridJwtDep` with `user_profile: AuthorizedUserProfileDep` in:
-  - [x] `get_tenant_mount_info()` (line ~23)
-  - [x] `create_tenant_mount_credentials()` (line ~88)
-  - [x] `revoke_tenant_mount_credentials()` (line ~244)
-  - [x] `list_tenant_mount_credentials()` (line ~326)
- [x] Verify no other code changes needed (parameter name and usage stays the same)
- [x] Run `just typecheck` to verify types
-
-#### Task 1.4: Protect proxy endpoints ✅
-**File**: `apps/cloud/src/basic_memory_cloud/api/proxy.py`
-
- [x] Update import: add `AuthorizedUserProfileDep` from `..deps`
- [x] Replace `user_profile: CurrentUserProfileHybridJwtDep` with `user_profile: AuthorizedUserProfileDep` in:
-  - [x] `check_tenant_health()` (line ~21)
-  - [x] `proxy_to_tenant()` (line ~63)
- [x] Verify no other code changes needed (parameter name and usage stays the same)
- [x] Run `just typecheck` to verify types
-
-**Why Keep /proxy Architecture:**
-
-The proxy layer is valuable because it:
-1. **Centralizes authorization** - Single place for JWT + subscription validation (closes both CLI and MCP auth gaps)
-2. **Handles tenant routing** - Maps tenant_id → fly_app_name without exposing infrastructure details
-3. **Abstracts infrastructure** - MCP and CLI don't need to know about Fly.io naming conventions
-4. **Enables features** - Can add rate limiting, caching, request logging, etc. at proxy layer
-5. **Supports both flows** - CLI tools and MCP tools both use /proxy endpoints
-
-The extra HTTP hop is minimal (< 10ms) and worth it for architectural benefits.
-
-**Performance Note:** Cloud app has Redis available - can cache subscription status to reduce database queries if needed. Initial implementation uses direct database query (simple, acceptable performance ~5-10ms).
-
-#### Task 1.5: Add unit tests for subscription service
-**File**: `apps/cloud/tests/services/test_subscription_service.py` (create if doesn't exist)
-
- [ ] Create test file if it doesn't exist
- [ ] Add test: `test_check_user_has_active_subscription_returns_true_for_active()`
-  - Create user with active subscription
-  - Call `check_user_has_active_subscription()`
-  - Assert returns `True`
- [ ] Add test: `test_check_user_has_active_subscription_returns_false_for_pending()`
-  - Create user with pending subscription
-  - Assert returns `False`
- [ ] Add test: `test_check_user_has_active_subscription_returns_false_for_cancelled()`
-  - Create user with cancelled subscription
-  - Assert returns `False`
- [ ] Add test: `test_check_user_has_active_subscription_returns_false_for_no_subscription()`
-  - Create user without subscription
-  - Assert returns `False`
- [ ] Run `just test` to verify tests pass
-
-#### Task 1.6: Add integration tests for dependency
-**File**: `apps/cloud/tests/test_deps.py` (create if doesn't exist)
-
- [ ] Create test file if it doesn't exist
- [ ] Add fixtures for mocking JWT credentials
- [ ] Add test: `test_authorized_cli_user_profile_with_active_subscription()`
-  - Mock valid JWT + active subscription
-  - Call dependency
-  - Assert returns UserProfile
- [ ] Add test: `test_authorized_cli_user_profile_without_subscription_raises_403()`
-  - Mock valid JWT + no subscription
-  - Assert raises HTTPException(403) with correct error detail
- [ ] Add test: `test_authorized_cli_user_profile_with_inactive_subscription_raises_403()`
-  - Mock valid JWT + cancelled subscription
-  - Assert raises HTTPException(403)
- [ ] Add test: `test_authorized_cli_user_profile_with_invalid_jwt_raises_401()`
-  - Mock invalid JWT
-  - Assert raises HTTPException(401)
- [ ] Run `just test` to verify tests pass
-
-#### Task 1.7: Deploy and verify cloud service
- [ ] Run `just check` to verify all quality checks pass
- [ ] Commit changes with message: "feat: add subscription validation to CLI endpoints"
- [ ] Deploy to preview environment: `flyctl deploy --config apps/cloud/fly.toml`
- [ ] Test manually:
-  - [ ] Call `/tenant/mount/info` with valid JWT but no subscription → expect 403
-  - [ ] Call `/tenant/mount/info` with valid JWT and active subscription → expect 200
-  - [ ] Verify error response structure matches spec
-
-### Phase 2: CLI (basic-memory)
-
-#### Task 2.1: Review and understand CLI authentication flow
-**Files**: `src/basic_memory/cli/commands/cloud/`
-
- [ ] Read `core_commands.py` to understand current login flow
- [ ] Read `api_client.py` to understand current error handling
- [ ] Identify where 403 errors should be caught
- [ ] Identify what error messages should be displayed
- [ ] Document current behavior in spec if needed
-
-#### Task 2.2: Update API client error handling
-**File**: `src/basic_memory/cli/commands/cloud/api_client.py`
-
- [ ] Add custom exception class `SubscriptionRequiredError` (or similar)
- [ ] Update HTTP error handling to parse 403 responses
- [ ] Extract `error`, `message`, and `subscribe_url` from error detail
- [ ] Raise specific exception for subscription_required errors
- [ ] Run `just typecheck` in basic-memory repo to verify types
-
-#### Task 2.3: Update CLI login command error handling
-**File**: `src/basic_memory/cli/commands/cloud/core_commands.py`
-
- [ ] Import the subscription error exception
- [ ] Wrap login flow with try/except for subscription errors
- [ ] Display user-friendly error message with rich console
- [ ] Show subscribe URL prominently
- [ ] Provide actionable next steps
- [ ] Run `just typecheck` to verify types
-
-**Expected error handling**:
-```python
-try:
-    # Existing login logic
-    success = await auth.login()
-    if success:
-        # Test access to protected endpoint
-        await api_client.test_connection()
-except SubscriptionRequiredError as e:
-    console.print("\n[red]✗ Subscription Required[/red]\n")
-    console.print(f"[yellow]{e.message}[/yellow]\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]")
-    raise typer.Exit(1)
-```
-
-#### Task 2.4: Update CLI tests
-**File**: `tests/cli/test_cloud_commands.py`
-
- [ ] Add test: `test_login_without_subscription_shows_error()`
-  - Mock 403 subscription_required response
-  - Call login command
-  - Assert error message displayed
-  - Assert subscribe URL shown
- [ ] Add test: `test_login_with_subscription_succeeds()`
-  - Mock successful authentication + subscription check
-  - Call login command
-  - Assert success message
- [ ] Run `just test` to verify tests pass
-
-#### Task 2.5: Update CLI documentation
-**File**: `docs/cloud-cli.md` (in basic-memory-docs repo)
-
- [ ] Add "Prerequisites" section if not present
- [ ] Document subscription requirement
- [ ] Add "Troubleshooting" section
- [ ] Document "Subscription Required" error
- [ ] Provide subscribe URL
- [ ] Add FAQ entry about subscription errors
- [ ] Build docs locally to verify formatting
-
-### Phase 3: End-to-End Testing
-
-#### Task 3.1: Create test user accounts
-**Prerequisites**: Access to WorkOS admin and database
-
- [ ] Create test user WITHOUT subscription:
-  - [ ] Sign up via WorkOS AuthKit
-  - [ ] Get workos_user_id from database
-  - [ ] Verify no subscription record exists
-  - [ ] Save credentials for testing
- [ ] Create test user WITH active subscription:
-  - [ ] Sign up via WorkOS AuthKit
-  - [ ] Create subscription via Polar or dev endpoint
-  - [ ] Verify subscription.status = "active" in database
-  - [ ] Save credentials for testing
-
-#### Task 3.2: Manual testing - User without subscription
-**Environment**: Preview/staging deployment
-
- [ ] Run `bm cloud login` with no-subscription user
- [ ] Verify: Login shows "Subscription Required" error
- [ ] Verify: Subscribe URL is displayed
- [ ] Verify: Cannot run `bm cloud setup`
- [ ] Verify: Cannot call `/tenant/mount/info` directly via curl
- [ ] Document any issues found
-
-#### Task 3.3: Manual testing - User with active subscription
-**Environment**: Preview/staging deployment
-
- [ ] Run `bm cloud login` with active-subscription user
- [ ] Verify: Login succeeds without errors
- [ ] Verify: Can run `bm cloud setup`
- [ ] Verify: Can call `/tenant/mount/info` successfully
- [ ] Verify: Can call `/proxy/*` endpoints successfully
- [ ] Document any issues found
-
-#### Task 3.4: Test subscription state transitions
-**Environment**: Preview/staging deployment + database access
-
- [ ] Start with active subscription user
- [ ] Verify: All operations work
- [ ] Update subscription.status to "cancelled" in database
- [ ] Verify: Login now shows "Subscription Required" error
- [ ] Verify: Existing tokens are rejected with 403
- [ ] Update subscription.status back to "active"
- [ ] Verify: Access restored immediately
- [ ] Document any issues found
-
-#### Task 3.5: Integration test suite
-**File**: `apps/cloud/tests/integration/test_cli_subscription_flow.py` (create if doesn't exist)
-
- [ ] Create integration test file
- [ ] Add test: `test_cli_flow_without_subscription()`
-  - Simulate full CLI flow without subscription
-  - Assert 403 at appropriate points
- [ ] Add test: `test_cli_flow_with_active_subscription()`
-  - Simulate full CLI flow with active subscription
-  - Assert all operations succeed
- [ ] Add test: `test_subscription_expiration_blocks_access()`
-  - Start with active subscription
-  - Change status to cancelled
-  - Assert access denied
- [ ] Run tests in CI/CD pipeline
- [ ] Document test coverage
-
-#### Task 3.6: Load/performance testing (optional)
-**Environment**: Staging environment
-
- [ ] Test subscription check performance under load
- [ ] Measure latency added by subscription check
- [ ] Verify database query performance
- [ ] Document any performance concerns
- [ ] Optimize if needed
-
-## Implementation Summary Checklist
-
-Use this high-level checklist to track overall progress:
-
-### Phase 1: Cloud Service 🔄
- [x] Add subscription check method to SubscriptionService
- [x] Add subscription validation dependency to deps.py
- [x] Add subscription_url config (env var)
- [x] Protect tenant mount endpoints (4 endpoints)
- [x] Protect proxy endpoints (2 endpoints)
- [ ] Add unit tests for subscription service
- [ ] Add integration tests for dependency
- [ ] Deploy and verify cloud service
-
-### Phase 2: CLI Updates 🔄
- [ ] Review CLI authentication flow
- [ ] Update API client error handling
- [ ] Update CLI login command error handling
- [ ] Add CLI tests
- [ ] Update CLI documentation
-
-### Phase 3: End-to-End Testing 🧪
- [ ] Create test user accounts
- [ ] Manual testing - user without subscription
- [ ] Manual testing - user with active subscription
- [ ] Test subscription state transitions
- [ ] Integration test suite
- [ ] Load/performance testing (optional)
-
-## Questions to Resolve
-
-### Resolved ✅
-
-1. **Admin Access**
-   - ✅ **Decision**: Admin users bypass subscription check
-   - **Rationale**: Admin endpoints already use `AdminUserHybridDep`, which is separate from CLI user endpoints
-   - **Implementation**: No changes needed to admin endpoints
-
-2. **Subscription Check Implementation**
-   - ✅ **Decision**: Use Option A (Database Check)
-   - **Rationale**: Simpler, faster to implement, works with existing infrastructure
-   - **Implementation**: Single JOIN query via `get_subscription_by_workos_user_id()`
-
-3. **Dependency Return Type**
-   - ✅ **Decision**: Return `UserProfile` (not `UserContext`)
-   - **Rationale**: Drop-in compatibility with existing endpoints, no refactoring needed
-   - **Implementation**: `AuthorizedCLIUserProfileDep` returns `UserProfile`
-
-### To Be Resolved ⏳
-
-1. **Subscription Check Frequency**
-   - **Options**:
-     - Check on every API call (slower, more secure) ✅ **RECOMMENDED**
-     - Cache subscription status (faster, risk of stale data)
-     - Check only on login/setup (fast, but allows expired subscriptions temporarily)
-   - **Recommendation**: Check on every call via dependency injection (simple, secure, acceptable performance)
-   - **Impact**: ~5-10ms per request (single indexed JOIN query)
-
-2. **Grace Period**
-   - **Options**:
-     - No grace period - immediate block when status != "active" ✅ **RECOMMENDED**
-     - 7-day grace period after period_end
-     - 14-day grace period after period_end
-   - **Recommendation**: No grace period initially, add later if needed based on customer feedback
-   - **Implementation**: Check `subscription.status == "active"` only (ignore period_end initially)
-
-3. **Subscription Expiration Handling**
-   - **Question**: Should we check `current_period_end < now()` in addition to `status == "active"`?
-   - **Options**:
-     - Only check status field (rely on Polar webhooks to update status) ✅ **RECOMMENDED**
-     - Check both status and current_period_end (more defensive)
-   - **Recommendation**: Only check status field, assume Polar webhooks keep it current
-   - **Risk**: If webhooks fail, expired subscriptions might retain access until webhook succeeds
-
-4. **Subscribe URL**
-   - **Question**: What's the actual subscription URL?
-   - **Current**: Spec uses `https://basicmemory.com/subscribe`
-   - **Action Required**: Verify correct URL before implementation
-
-5. **Dev Mode / Testing Bypass**
-   - **Question**: Support bypass for development/testing?
-   - **Options**:
-     - Environment variable: `DISABLE_SUBSCRIPTION_CHECK=true`
-     - Always enforce (more realistic testing) ✅ **RECOMMENDED**
-   - **Recommendation**: No bypass - use test users with real subscriptions for realistic testing
-   - **Implementation**: Create dev endpoint to activate subscriptions for testing
-
-## Related Specs
-
- SPEC-9: Multi-Project Bidirectional Sync Architecture (CLI affected by this change)
- SPEC-8: TigrisFS Integration (Mount endpoints protected)
-
-## Notes
-
- This spec prioritizes security over convenience - better to block unauthorized access than risk revenue loss
- Clear error messages are critical - users should understand why they're blocked and how to resolve it
- Consider adding telemetry to track subscription_required errors for monitoring signup conversion
@@ -1,210 +0,0 @@
---
-title: 'SPEC-14: Cloud Git Versioning & GitHub Backup'
-type: spec
-permalink: specs/spec-14-cloud-git-versioning
-tags:
- git
- github
- backup
- versioning
- cloud
-related:
- specs/spec-9-multi-project-bisync
- specs/spec-9-follow-ups-conflict-sync-and-observability
-status: deferred
---
-
-# SPEC-14: Cloud Git Versioning & GitHub Backup
-
-**Status: DEFERRED** - Postponed until multi-user/teams feature development. Using S3 versioning (SPEC-9.1) for v1 instead.
-
-## Why Deferred
-
-**Original goals can be met with simpler solutions:**
- Version history → **S3 bucket versioning** (automatic, zero config)
- Offsite backup → **Tigris global replication** (built-in)
- Restore capability → **S3 version restore** (`bm cloud restore --version-id`)
- Collaboration → **Deferred to teams/multi-user feature** (not v1 requirement)
-
-**Complexity vs value trade-off:**
- Git integration adds: committer service, puller service, webhooks, LFS, merge conflicts
- Risk: Loop detection between Git ↔ rclone bisync ↔ local edits
- S3 versioning gives 80% of value with 5% of complexity
-
-**When to revisit:**
- Teams/multi-user features (PR-based collaboration workflow)
- User requests for commit messages and branch-based workflows
- Need for fine-grained audit trail beyond S3 object metadata
-
---
-
-## Original Specification (for reference)
-
-## Why
-Early access users want **transparent version history**, easy **offsite backup**, and a familiar **restore/branching** workflow. Git/GitHub integration would provide:
- Auditable history of every change (who/when/why)
- Branches/PRs for review and collaboration
- Offsite private backup under the user's control
- Escape hatch: users can always `git clone` their knowledge base
-
-**Note:** These goals are now addressed via S3 versioning (SPEC-9.1) for single-user use case.
-
-## Goals
- **Transparent**: Users keep using Basic Memory; Git runs behind the scenes.
- **Private**: Push to a **private GitHub repo** that the user owns (or tenant org).
- **Reliable**: No data loss, deterministic mapping of filesystem ↔ Git.
- **Composable**: Plays nicely with SPEC‑9 bisync and upcoming conflict features (SPEC‑9 Follow‑Ups).
-
-**Non‑Goals (for v1):**
- Fine‑grained per‑file encryption in Git history (can be layered later).
- Large media optimization beyond Git LFS defaults.
-
-## User Stories
-1. *As a user*, I connect my GitHub and choose a private backup repo.
-2. *As a user*, every change I make in cloud (or via bisync) is **committed** and **pushed** automatically.
-3. *As a user*, I can **restore** a file/folder/project to a prior version.
-4. *As a power user*, I can **git pull/push** directly to collaborate outside the app.
-5. *As an admin*, I can enforce repo ownership (tenant org) and least‑privilege scopes.
-
-## Scope
- **In scope:** Full repo backup of `/app/data/` (all projects) with optional selective subpaths.
- **Out of scope (v1):** Partial shallow mirrors; encrypted Git; cross‑provider SCM (GitLab/Bitbucket).
-
-## Architecture
-### Topology
- **Authoritative working tree**: `/app/data/` (bucket mount) remains the source of truth (SPEC‑9).
- **Bare repo** lives alongside: `/app/git/${tenant}/knowledge.git` (server‑side).
- **Mirror remote**: `github.com/<owner>/<repo>.git` (private).
-
-```mermaid
-flowchart LR
-  A[/Users & Agents/] -->|writes/edits| B[/app/data/]
-  B -->|file events| C[Committer Service]
-  C -->|git commit| D[(Bare Repo)]
-  D -->|push| E[(GitHub Private Repo)]
-  E -->|webhook (push)| F[Puller Service]
-  F -->|git pull/merge| D
-  D -->|checkout/merge| B
-```
-
-### Services
- **Committer Service** (daemon):
-  - Watches `/app/data/` for changes (inotify/poll)
-  - Batches changes (debounce e.g. 2–5s)
-  - Writes `.bmmeta` (if present) into commit message trailer (see Follow‑Ups)
-  - `git add -A && git commit -m "chore(sync): <summary>
-
-BM-Meta: <json>"`
-  - Periodic `git push` to GitHub mirror (configurable interval)
- **Puller Service** (webhook target):
-  - Receives GitHub webhook (push) → `git fetch`
-  - **Fast‑forward** merges to `main` only; reject non‑FF unless policy allows
-  - Applies changes back to `/app/data/` via clean checkout
-  - Emits sync events for Basic Memory indexers
-
-### Auth & Security
- **GitHub App** (recommended): minimal scopes: `contents:read/write`, `metadata:read`, webhook.
- Tenant‑scoped installation; repo created in user account or tenant org.
- Tokens stored in KMS/secret manager; rotated automatically.
- Optional policy: allow only **FF merges** on `main`; non‑FF requires PR.
-
-### Repo Layout
- **Monorepo** (default): one repo per tenant mirrors `/app/data/` with subfolders per project.
- Optional multi‑repo mode (later): one repo per project.
-
-### File Handling
- Honor `.gitignore` generated from `.bmignore.rclone` + BM defaults (cache, temp, state).
- **Git LFS** for large binaries (images, media) — auto track by extension/size threshold.
- Normalize newline + Unicode (aligns with Follow‑Ups).
-
-### Conflict Model
- **Primary concurrency**: SPEC‑9 Follow‑Ups (`.bmmeta`, conflict copies) stays the first line of defense.
- **Git merges** are a **secondary** mechanism:
-  - Server only auto‑merges **text** conflicts when trivial (FF or clean 3‑way).
-  - Otherwise, create `name (conflict from <branch>, <ts>).md` and surface via events.
-
-### Data Flow vs Bisync
- Bisync (rclone) continues between local sync dir ↔ bucket.
- Git sits **cloud‑side** between bucket and GitHub.
- On **pull** from GitHub → files written to `/app/data/` → picked up by indexers & eventually by bisync back to users.
-
-## CLI & UX
-New commands (cloud mode):
- `bm cloud git connect` — Launch GitHub App installation; create private repo; store installation id.
- `bm cloud git status` — Show connected repo, last push time, last webhook delivery, pending commits.
- `bm cloud git push` — Manual push (rarely needed).
- `bm cloud git pull` — Manual pull/FF (admin only by default).
- `bm cloud snapshot -m "message"` — Create a tagged point‑in‑time snapshot (git tag).
- `bm restore <path> --to <commit|tag>` — Restore file/folder/project to prior version.
-
-Settings:
- `bm config set git.autoPushInterval=5s`
- `bm config set git.lfs.sizeThreshold=10MB`
- `bm config set git.allowNonFF=false`
-
-## Migration & Backfill
- On connect, if repo empty: initial commit of entire `/app/data/`.
- If repo has content: require **one‑time import** path (clone to staging, reconcile, choose direction).
-
-## Edge Cases
- Massive deletes: gated by SPEC‑9 `max_delete` **and** Git pre‑push hook checks.
- Case changes and rename detection: rely on git rename heuristics + Follow‑Ups move hints.
- Secrets: default ignore common secret patterns; allow custom deny list.
-
-## Telemetry & Observability
- Emit `git_commit`, `git_push`, `git_pull`, `git_conflict` events with correlation IDs.
- `bm sync --report` extended with Git stats (commit count, delta bytes, push latency).
-
-## Phased Plan
-### Phase 0 — Prototype (1 sprint)
- Server: bare repo init + simple committer (batch every 10s) + manual GitHub token.
- CLI: `bm cloud git connect --token <PAT>` (dev‑only)
- Success: edits in `/app/data/` appear in GitHub within 30s.
-
-### Phase 1 — GitHub App & Webhooks (1–2 sprints)
- Switch to GitHub App installs; create private repo; store installation id.
- Committer hardened (debounce 2–5s, backoff, retries).
- Puller service with webhook → FF merge → checkout to `/app/data/`.
- LFS auto‑track + `.gitignore` generation.
- CLI surfaces status + logs.
-
-### Phase 2 — Restore & Snapshots (1 sprint)
- `bm restore` for file/folder/project with dry‑run.
- `bm cloud snapshot` tags + list/inspect.
- Policy: PR‑only non‑FF, admin override.
-
-### Phase 3 — Selective & Multi‑Repo (nice‑to‑have)
- Include/exclude projects; optional per‑project repos.
- Advanced policies (branch protections, required reviews).
-
-## Acceptance Criteria
- Changes to `/app/data/` are committed and pushed automatically within configurable interval (default ≤5s).
- GitHub webhook pull results in updated files in `/app/data/` (FF‑only by default).
- LFS configured and functioning; large files don't bloat history.
- `bm cloud git status` shows connected repo and last push/pull times.
- `bm restore` restores a file/folder to a prior commit with a clear audit trail.
- End‑to‑end works alongside SPEC‑9 bisync without loops or data loss.
-
-## Risks & Mitigations
- **Loop risk (Git ↔ Bisync)**: Writes to `/app/data/` → bisync → local → user edits → back again. *Mitigation*: Debounce, commit squashing, idempotent `.bmmeta` versioning, and watch exclusion windows during pull.
- **Repo bloat**: Lots of binary churn. *Mitigation*: default LFS, size threshold, optional media‑only repo later.
- **Security**: Token leakage. *Mitigation*: GitHub App with short‑lived tokens, KMS storage, scoped permissions.
- **Merge complexity**: Non‑trivial conflicts. *Mitigation*: prefer FF; otherwise conflict copies + events; require PR for non‑FF.
-
-## Open Questions
- Do we default to **monorepo** per tenant, or offer project‑per‑repo at connect time?
- Should `restore` write to a branch and open a PR, or directly modify `main`?
- How do we expose Git history in UI (timeline view) without users dropping to CLI?
-
-## Appendix: Sample Config
-```json
-{
-  "git": {
-    "enabled": true,
-    "repo": "https://github.com/<owner>/<repo>.git",
-    "autoPushInterval": "5s",
-    "allowNonFF": false,
-    "lfs": { "sizeThreshold": 10485760 }
-  }
-}
-```
@@ -1,210 +0,0 @@
---
-title: 'SPEC-14: Cloud Git Versioning & GitHub Backup'
-type: spec
-permalink: specs/spec-14-cloud-git-versioning
-tags:
- git
- github
- backup
- versioning
- cloud
-related:
- specs/spec-9-multi-project-bisync
- specs/spec-9-follow-ups-conflict-sync-and-observability
-status: deferred
---
-
-# SPEC-14: Cloud Git Versioning & GitHub Backup
-
-**Status: DEFERRED** - Postponed until multi-user/teams feature development. Using S3 versioning (SPEC-9.1) for v1 instead.
-
-## Why Deferred
-
-**Original goals can be met with simpler solutions:**
- Version history → **S3 bucket versioning** (automatic, zero config)
- Offsite backup → **Tigris global replication** (built-in)
- Restore capability → **S3 version restore** (`bm cloud restore --version-id`)
- Collaboration → **Deferred to teams/multi-user feature** (not v1 requirement)
-
-**Complexity vs value trade-off:**
- Git integration adds: committer service, puller service, webhooks, LFS, merge conflicts
- Risk: Loop detection between Git ↔ rclone bisync ↔ local edits
- S3 versioning gives 80% of value with 5% of complexity
-
-**When to revisit:**
- Teams/multi-user features (PR-based collaboration workflow)
- User requests for commit messages and branch-based workflows
- Need for fine-grained audit trail beyond S3 object metadata
-
---
-
-## Original Specification (for reference)
-
-## Why
-Early access users want **transparent version history**, easy **offsite backup**, and a familiar **restore/branching** workflow. Git/GitHub integration would provide:
- Auditable history of every change (who/when/why)
- Branches/PRs for review and collaboration
- Offsite private backup under the user's control
- Escape hatch: users can always `git clone` their knowledge base
-
-**Note:** These goals are now addressed via S3 versioning (SPEC-9.1) for single-user use case.
-
-## Goals
- **Transparent**: Users keep using Basic Memory; Git runs behind the scenes.
- **Private**: Push to a **private GitHub repo** that the user owns (or tenant org).
- **Reliable**: No data loss, deterministic mapping of filesystem ↔ Git.
- **Composable**: Plays nicely with SPEC‑9 bisync and upcoming conflict features (SPEC‑9 Follow‑Ups).
-
-**Non‑Goals (for v1):**
- Fine‑grained per‑file encryption in Git history (can be layered later).
- Large media optimization beyond Git LFS defaults.
-
-## User Stories
-1. *As a user*, I connect my GitHub and choose a private backup repo.
-2. *As a user*, every change I make in cloud (or via bisync) is **committed** and **pushed** automatically.
-3. *As a user*, I can **restore** a file/folder/project to a prior version.
-4. *As a power user*, I can **git pull/push** directly to collaborate outside the app.
-5. *As an admin*, I can enforce repo ownership (tenant org) and least‑privilege scopes.
-
-## Scope
- **In scope:** Full repo backup of `/app/data/` (all projects) with optional selective subpaths.
- **Out of scope (v1):** Partial shallow mirrors; encrypted Git; cross‑provider SCM (GitLab/Bitbucket).
-
-## Architecture
-### Topology
- **Authoritative working tree**: `/app/data/` (bucket mount) remains the source of truth (SPEC‑9).
- **Bare repo** lives alongside: `/app/git/${tenant}/knowledge.git` (server‑side).
- **Mirror remote**: `github.com/<owner>/<repo>.git` (private).
-
-```mermaid
-flowchart LR
-  A[/Users & Agents/] -->|writes/edits| B[/app/data/]
-  B -->|file events| C[Committer Service]
-  C -->|git commit| D[(Bare Repo)]
-  D -->|push| E[(GitHub Private Repo)]
-  E -->|webhook (push)| F[Puller Service]
-  F -->|git pull/merge| D
-  D -->|checkout/merge| B
-```
-
-### Services
- **Committer Service** (daemon):
-  - Watches `/app/data/` for changes (inotify/poll)
-  - Batches changes (debounce e.g. 2–5s)
-  - Writes `.bmmeta` (if present) into commit message trailer (see Follow‑Ups)
-  - `git add -A && git commit -m "chore(sync): <summary>
-
-BM-Meta: <json>"`
-  - Periodic `git push` to GitHub mirror (configurable interval)
- **Puller Service** (webhook target):
-  - Receives GitHub webhook (push) → `git fetch`
-  - **Fast‑forward** merges to `main` only; reject non‑FF unless policy allows
-  - Applies changes back to `/app/data/` via clean checkout
-  - Emits sync events for Basic Memory indexers
-
-### Auth & Security
- **GitHub App** (recommended): minimal scopes: `contents:read/write`, `metadata:read`, webhook.
- Tenant‑scoped installation; repo created in user account or tenant org.
- Tokens stored in KMS/secret manager; rotated automatically.
- Optional policy: allow only **FF merges** on `main`; non‑FF requires PR.
-
-### Repo Layout
- **Monorepo** (default): one repo per tenant mirrors `/app/data/` with subfolders per project.
- Optional multi‑repo mode (later): one repo per project.
-
-### File Handling
- Honor `.gitignore` generated from `.bmignore.rclone` + BM defaults (cache, temp, state).
- **Git LFS** for large binaries (images, media) — auto track by extension/size threshold.
- Normalize newline + Unicode (aligns with Follow‑Ups).
-
-### Conflict Model
- **Primary concurrency**: SPEC‑9 Follow‑Ups (`.bmmeta`, conflict copies) stays the first line of defense.
- **Git merges** are a **secondary** mechanism:
-  - Server only auto‑merges **text** conflicts when trivial (FF or clean 3‑way).
-  - Otherwise, create `name (conflict from <branch>, <ts>).md` and surface via events.
-
-### Data Flow vs Bisync
- Bisync (rclone) continues between local sync dir ↔ bucket.
- Git sits **cloud‑side** between bucket and GitHub.
- On **pull** from GitHub → files written to `/app/data/` → picked up by indexers & eventually by bisync back to users.
-
-## CLI & UX
-New commands (cloud mode):
- `bm cloud git connect` — Launch GitHub App installation; create private repo; store installation id.
- `bm cloud git status` — Show connected repo, last push time, last webhook delivery, pending commits.
- `bm cloud git push` — Manual push (rarely needed).
- `bm cloud git pull` — Manual pull/FF (admin only by default).
- `bm cloud snapshot -m "message"` — Create a tagged point‑in‑time snapshot (git tag).
- `bm restore <path> --to <commit|tag>` — Restore file/folder/project to prior version.
-
-Settings:
- `bm config set git.autoPushInterval=5s`
- `bm config set git.lfs.sizeThreshold=10MB`
- `bm config set git.allowNonFF=false`
-
-## Migration & Backfill
- On connect, if repo empty: initial commit of entire `/app/data/`.
- If repo has content: require **one‑time import** path (clone to staging, reconcile, choose direction).
-
-## Edge Cases
- Massive deletes: gated by SPEC‑9 `max_delete` **and** Git pre‑push hook checks.
- Case changes and rename detection: rely on git rename heuristics + Follow‑Ups move hints.
- Secrets: default ignore common secret patterns; allow custom deny list.
-
-## Telemetry & Observability
- Emit `git_commit`, `git_push`, `git_pull`, `git_conflict` events with correlation IDs.
- `bm sync --report` extended with Git stats (commit count, delta bytes, push latency).
-
-## Phased Plan
-### Phase 0 — Prototype (1 sprint)
- Server: bare repo init + simple committer (batch every 10s) + manual GitHub token.
- CLI: `bm cloud git connect --token <PAT>` (dev‑only)
- Success: edits in `/app/data/` appear in GitHub within 30s.
-
-### Phase 1 — GitHub App & Webhooks (1–2 sprints)
- Switch to GitHub App installs; create private repo; store installation id.
- Committer hardened (debounce 2–5s, backoff, retries).
- Puller service with webhook → FF merge → checkout to `/app/data/`.
- LFS auto‑track + `.gitignore` generation.
- CLI surfaces status + logs.
-
-### Phase 2 — Restore & Snapshots (1 sprint)
- `bm restore` for file/folder/project with dry‑run.
- `bm cloud snapshot` tags + list/inspect.
- Policy: PR‑only non‑FF, admin override.
-
-### Phase 3 — Selective & Multi‑Repo (nice‑to‑have)
- Include/exclude projects; optional per‑project repos.
- Advanced policies (branch protections, required reviews).
-
-## Acceptance Criteria
- Changes to `/app/data/` are committed and pushed automatically within configurable interval (default ≤5s).
- GitHub webhook pull results in updated files in `/app/data/` (FF‑only by default).
- LFS configured and functioning; large files don't bloat history.
- `bm cloud git status` shows connected repo and last push/pull times.
- `bm restore` restores a file/folder to a prior commit with a clear audit trail.
- End‑to‑end works alongside SPEC‑9 bisync without loops or data loss.
-
-## Risks & Mitigations
- **Loop risk (Git ↔ Bisync)**: Writes to `/app/data/` → bisync → local → user edits → back again. *Mitigation*: Debounce, commit squashing, idempotent `.bmmeta` versioning, and watch exclusion windows during pull.
- **Repo bloat**: Lots of binary churn. *Mitigation*: default LFS, size threshold, optional media‑only repo later.
- **Security**: Token leakage. *Mitigation*: GitHub App with short‑lived tokens, KMS storage, scoped permissions.
- **Merge complexity**: Non‑trivial conflicts. *Mitigation*: prefer FF; otherwise conflict copies + events; require PR for non‑FF.
-
-## Open Questions
- Do we default to **monorepo** per tenant, or offer project‑per‑repo at connect time?
- Should `restore` write to a branch and open a PR, or directly modify `main`?
- How do we expose Git history in UI (timeline view) without users dropping to CLI?
-
-## Appendix: Sample Config
-```json
-{
-  "git": {
-    "enabled": true,
-    "repo": "https://github.com/<owner>/<repo>.git",
-    "autoPushInterval": "5s",
-    "allowNonFF": false,
-    "lfs": { "sizeThreshold": 10485760 }
-  }
-}
-```
@@ -1,273 +0,0 @@
---
-title: 'SPEC-15: Configuration Persistence via Tigris for Cloud Tenants'
-type: spec
-permalink: specs/spec-14-config-persistence-tigris
-tags:
- persistence
- tigris
- multi-tenant
- infrastructure
- configuration
-status: draft
---
-
-# SPEC-15: Configuration Persistence via Tigris for Cloud Tenants
-
-## Why
-
-We need to persist Basic Memory configuration across Fly.io deployments without using persistent volumes or external databases.
-
-**Current Problems:**
- `~/.basic-memory/config.json` lost on every deployment (project configuration)
- `~/.basic-memory/memory.db` lost on every deployment (search index)
- Persistent volumes break clean deployment workflow
- External databases (Turso) require per-tenant token management
-
-**The Insight:**
-The SQLite database is just an **index cache** of the markdown files. It can be rebuilt in seconds from the source markdown files in Tigris. Only the small `config.json` file needs true persistence.
-
-**Solution:**
- Store `config.json` in Tigris bucket (persistent, small file)
- Rebuild `memory.db` on startup from markdown files (fast, ephemeral)
- No persistent volumes, no external databases, no token management
-
-## What
-
-Store Basic Memory configuration in the Tigris bucket and rebuild the database index on tenant machine startup.
-
-**Affected Components:**
- `basic-memory/src/basic_memory/config.py` - Add configurable config directory
-
-**Architecture:**
-
-```bash
-# Tigris Bucket (persistent, mounted at /app/data)
-/app/data/
-  ├── .basic-memory/
-  │   └── config.json          # ← Project configuration (persistent, accessed via BASIC_MEMORY_CONFIG_DIR)
-  └── basic-memory/             # ← Markdown files (persistent, BASIC_MEMORY_HOME)
-      ├── project1/
-      └── project2/
-
-# Fly Machine (ephemeral)
-/app/.basic-memory/
-  └── memory.db                # ← Rebuilt on startup (fast local disk)
-```
-
-## How (High Level)
-
-### 1. Add Configurable Config Directory to Basic Memory
-
-Currently `ConfigManager` hardcodes `~/.basic-memory/config.json`. Add environment variable to override:
-
-```python
-# basic-memory/src/basic_memory/config.py
-
-class ConfigManager:
-    """Manages Basic Memory configuration."""
-
-    def __init__(self) -> None:
-        """Initialize the configuration manager."""
-        home = os.getenv("HOME", Path.home())
-        if isinstance(home, str):
-            home = Path(home)
-
-        # Allow override via environment variable
-        if config_dir := os.getenv("BASIC_MEMORY_CONFIG_DIR"):
-            self.config_dir = Path(config_dir)
-        else:
-            self.config_dir = home / DATA_DIR_NAME
-
-        self.config_file = self.config_dir / CONFIG_FILE_NAME
-
-        # Ensure config directory exists
-        self.config_dir.mkdir(parents=True, exist_ok=True)
-```
-
-### 2. Rebuild Database on Startup
-
-Basic Memory already has the sync functionality. Just ensure it runs on startup:
-
-```python
-# apps/api/src/basic_memory_cloud_api/main.py
-
-@app.on_event("startup")
-async def startup_sync():
-    """Rebuild database index from Tigris markdown files."""
-    logger.info("Starting database rebuild from Tigris")
-
-    # Initialize file sync (rebuilds index from markdown files)
-    app_config = ConfigManager().config
-    await initialize_file_sync(app_config)
-
-    logger.info("Database rebuild complete")
-```
-
-### 3. Environment Configuration
-
-```bash
-# Machine environment variables
-BASIC_MEMORY_CONFIG_DIR=/app/data/.basic-memory  # Config read/written directly to Tigris
-# memory.db stays in default location: /app/.basic-memory/memory.db (local ephemeral disk)
-```
-
-## Implementation Task List
-
-### Phase 1: Basic Memory Changes ✅
- [x] Add `BASIC_MEMORY_CONFIG_DIR` environment variable support to `ConfigManager.__init__()`
- [x] Test config loading from custom directory
- [x] Update tests to verify custom config dir works
-
-### Phase 2: Tigris Bucket Structure ✅
- [x] Ensure `.basic-memory/` directory exists in Tigris bucket on tenant creation
-  - ✅ ConfigManager auto-creates on first run, no explicit provisioning needed
- [x] Initialize `config.json` in Tigris on first tenant deployment
-  - ✅ ConfigManager creates config.json automatically in BASIC_MEMORY_CONFIG_DIR
- [x] Verify TigrisFS handles hidden directories correctly
-  - ✅ TigrisFS supports hidden directories (verified in SPEC-8)
-
-### Phase 3: Deployment Integration ✅
- [x] Set `BASIC_MEMORY_CONFIG_DIR` environment variable in machine deployment
-  - ✅ Added to BasicMemoryMachineConfigBuilder in fly_schemas.py
- [x] Ensure database rebuild runs on machine startup via initialization sync
-  - ✅ sync_worker.py runs initialize_file_sync every 30s (already implemented)
- [x] Handle first-time tenant setup (no config exists yet)
-  - ✅ ConfigManager creates config.json on first initialization
- [ ] Test deployment workflow with config persistence
-
-### Phase 4: Testing
- [x] Unit tests for config directory override
- [-] Integration test: deploy → write config → redeploy → verify config persists
- [ ] Integration test: deploy → add project → redeploy → verify project in config
- [ ] Performance test: measure db rebuild time on startup
-
-### Phase 5: Documentation
- [ ] Document config persistence architecture
- [ ] Update deployment runbook
- [ ] Document startup sequence and timing
-
-## How to Evaluate
-
-### Success Criteria
-
-1. **Config Persistence**
-   - [ ] config.json persists across deployments
-   - [ ] Projects list maintained across restarts
-   - [ ] No manual configuration needed after redeploy
-
-2. **Database Rebuild**
-   - [ ] memory.db rebuilt on startup in < 30 seconds
-   - [ ] All entities indexed correctly
-   - [ ] Search functionality works after rebuild
-
-3. **Performance**
-   - [ ] SQLite queries remain fast (local disk)
-   - [ ] Config reads acceptable (symlink to Tigris)
-   - [ ] No noticeable performance degradation
-
-4. **Deployment Workflow**
-   - [ ] Clean deployments without volumes
-   - [ ] No new external dependencies
-   - [ ] No secret management needed
-
-### Testing Procedure
-
-1. **Config Persistence Test**
-   ```bash
-   # Deploy tenant
-   POST /tenants → tenant_id
-
-   # Add a project
-   basic-memory project add "test-project" ~/test
-
-   # Verify config has project
-   cat /app/data/.basic-memory/config.json
-
-   # Redeploy machine
-   fly deploy --app basic-memory-{tenant_id}
-
-   # Verify project still exists
-   basic-memory project list
-   ```
-
-2. **Database Rebuild Test**
-   ```bash
-   # Create notes
-   basic-memory write "Test Note" --content "..."
-
-   # Redeploy (db lost)
-   fly deploy --app basic-memory-{tenant_id}
-
-   # Wait for startup sync
-   sleep 10
-
-   # Verify note is indexed
-   basic-memory search "Test Note"
-   ```
-
-3. **Performance Benchmark**
-   ```bash
-   # Time the startup sync
-   time basic-memory sync
-
-   # Should be < 30 seconds for typical tenant
-   ```
-
-## Benefits Over Alternatives
-
-**vs. Persistent Volumes:**
- ✅ Clean deployment workflow
- ✅ No volume migration needed
- ✅ Simpler infrastructure
-
-**vs. Turso (External Database):**
- ✅ No per-tenant token management
- ✅ No external service dependencies
- ✅ No additional costs
- ✅ Simpler architecture
-
-**vs. SQLite on FUSE:**
- ✅ Fast local SQLite performance
- ✅ Only slow reads for small config file
- ✅ Database queries remain fast
-
-## Implementation Assignment
-
-**Primary Agent:** `python-developer`
- Add `BASIC_MEMORY_CONFIG_DIR` environment variable to ConfigManager
- Update deployment workflow to set environment variable
- Ensure startup sync runs correctly
-
-**Review Agent:** `system-architect`
- Validate architecture simplicity
- Review performance implications
- Assess startup timing
-
-## Dependencies
-
- **Internal:** TigrisFS must be working and stable
- **Internal:** Basic Memory sync must be reliable
- **Internal:** SPEC-8 (TigrisFS Integration) must be complete
-
-## Open Questions
-
-1. Should we add a health check that waits for db rebuild to complete?
-2. Do we need to handle very large knowledge bases (>10k entities) differently?
-3. Should we add metrics for startup sync duration?
-
-## References
-
- Basic Memory sync: `basic-memory/src/basic_memory/services/initialization.py`
- Config management: `basic-memory/src/basic_memory/config.py`
- TigrisFS integration: SPEC-8
-
---
-
-**Status Updates:**
-
- 2025-10-08: Pivoted from Turso to Tigris-based config persistence
- 2025-10-08: Phase 1 complete - BASIC_MEMORY_CONFIG_DIR support added (PR #343)
- 2025-10-08: Phases 2-3 complete - Added BASIC_MEMORY_CONFIG_DIR to machine config
-  - Config now persists to /app/data/.basic-memory/config.json in Tigris bucket
-  - Database rebuild already working via sync_worker.py
-  - Ready for deployment testing (Phase 4)
@@ -1,800 +0,0 @@
---
-title: 'SPEC-16: MCP Cloud Service Consolidation'
-type: spec
-permalink: specs/spec-16-mcp-cloud-service-consolidation
-tags:
- architecture
- mcp
- cloud
- performance
- deployment
-status: in-progress
---
-
-## Status Update
-
-**Phase 0 (Basic Memory Refactor): ✅ COMPLETE**
- basic-memory PR #344: async_client context manager pattern implemented
- All 17 MCP tools updated to use `async with get_client() as client:`
- CLI commands updated to use context manager
- Removed `inject_auth_header()` and `headers.py` (~100 lines deleted)
- Factory pattern enables clean dependency injection
- Tests passing, typecheck clean
-
-**Phase 0 Integration: ✅ COMPLETE**
- basic-memory-cloud updated to use async-client-context-manager branch
- Implemented `tenant_direct_client_factory()` with proper context manager pattern
- Removed module-level client override hacks
- Removed unnecessary `/proxy` prefix stripping (tools pass relative URLs)
- Typecheck and lint passing with proper noqa hints
- MCP tools confirmed working via inspector (local testing)
-
-**Phase 1 (Code Consolidation): ✅ COMPLETE**
- MCP server mounted on Cloud FastAPI app at /mcp endpoint
- AuthKitProvider configured with WorkOS settings
- Combined lifespans (Cloud + MCP) working correctly
- JWT context middleware integrated
- All routes and MCP tools functional
-
-**Phase 2 (Direct Tenant Transport): ✅ COMPLETE**
- TenantDirectTransport implemented with custom httpx transport
- Per-request JWT extraction via FastMCP DI
- Tenant lookup and signed header generation working
- Direct routing to tenant APIs (eliminating HTTP hop)
- Transport tests passing (11/11)
-
-**Phase 3 (Testing & Validation): ✅ COMPLETE**
- Typecheck and lint passing across all services
- MCP OAuth authentication working in preview environment
- Tenant isolation via signed headers verified
- Fixed BM_TENANT_HEADER_SECRET mismatch between environments
- MCP tools successfully calling tenant APIs in preview
-
-**Phase 4 (Deployment Configuration): ✅ COMPLETE**
- Updated apps/cloud/fly.template.toml with MCP environment variables
- Added HTTP/2 backend support for better MCP performance
- Added OAuth protected resource health check
- Removed MCP from preview deployment workflow
- Successfully deployed to preview environment (PR #113)
- All services operational at pr-113-basic-memory-cloud.fly.dev
-
-**Next Steps:**
- Phase 5: Cleanup (remove apps/mcp directory)
- Phase 6: Production rollout and performance measurement
-
-# SPEC-16: MCP Cloud Service Consolidation
-
-## Why
-
-### Original Architecture Constraints (Now Removed)
-
-The current architecture deploys MCP Gateway and Cloud Service as separate Fly.io apps:
-
-**Current Flow:**
-```
-LLM Client → MCP Gateway (OAuth) → Cloud Proxy (JWT + header signing) → Tenant API (JWT + header validation)
-            apps/mcp                apps/cloud /proxy                    apps/api
-```
-
-This separation was originally necessary because:
-1. **Stateful SSE requirement** - MCP needed server-sent events with session state for active project tracking
-2. **fastmcp.run limitation** - The FastMCP demo helper didn't support worker processes
-
-### Why These Constraints No Longer Apply
-
-1. **State externalized** - Project state moved from in-memory to LLM context (external state)
-2. **HTTP transport enabled** - Switched from SSE to stateless HTTP for MCP tools
-3. **Worker support added** - Converted from `fastmcp.run()` to `uvicorn.run()` with workers
-
-### Current Problems
-
- **Unnecessary HTTP hop** - MCP tools call Cloud /proxy endpoint which calls tenant API
- **Higher latency** - Extra network round trip for every MCP operation
- **Increased costs** - Two separate Fly.io apps instead of one
- **Complex deployment** - Two services to deploy, monitor, and maintain
- **Resource waste** - Separate database connections, HTTP clients, telemetry overhead
-
-## What
-
-### Services Affected
-
-1. **apps/mcp** - MCP Gateway service (to be merged)
-2. **apps/cloud** - Cloud service (will receive MCP functionality)
-3. **basic-memory** - Update `async_client.py` to use direct calls
-4. **Deployment** - Consolidate Fly.io deployment to single app
-
-### Components Changed
-
-**Merged:**
- MCP middleware and telemetry into Cloud app
- MCP tools mounted on Cloud FastAPI instance
- ProxyService used directly by MCP tools (not via HTTP)
-
-**Kept:**
- `/proxy` endpoint (still needed by web UI)
- All existing Cloud routes (provisioning, webhooks, etc.)
- Dual validation in tenant API (JWT + signed headers)
-
-**Removed:**
- apps/mcp directory
- Separate MCP Fly.io deployment
- HTTP calls from MCP tools to /proxy endpoint
-
-## How (High Level)
-
-### 1. Mount FastMCP on Cloud FastAPI App
-
-```python
-# apps/cloud/src/basic_memory_cloud/main.py
-
-from basic_memory.mcp.server import mcp
-from basic_memory_cloud_mcp.middleware import TelemetryMiddleware
-
-# Configure MCP OAuth
-auth_provider = AuthKitProvider(
-    authkit_domain=settings.authkit_domain,
-    base_url=settings.authkit_base_url,
-    required_scopes=[],
-)
-mcp.auth = auth_provider
-mcp.add_middleware(TelemetryMiddleware())
-
-# Mount MCP at /mcp endpoint
-mcp_app = mcp.http_app(path="/mcp", stateless_http=True)
-app.mount("/mcp", mcp_app)
-
-# Existing Cloud routes stay at root
-app.include_router(proxy_router)
-app.include_router(provisioning_router)
-# ... etc
-```
-
-### 2. Direct Tenant Transport (No HTTP Hop)
-
-Instead of calling `/proxy`, MCP tools call tenant APIs directly via custom httpx transport.
-
-**Important:** No URL prefix stripping needed. The transport receives relative URLs like `/main/resource/notes/my-note` which are correctly routed to tenant APIs. The `/proxy` prefix only exists for web UI requests to the proxy router, not for MCP tools using the custom transport.
-
-```python
-# apps/cloud/src/basic_memory_cloud/transports/tenant_direct.py
-
-from httpx import AsyncBaseTransport, Request, Response
-from fastmcp.server.dependencies import get_http_headers
-import jwt
-
-class TenantDirectTransport(AsyncBaseTransport):
-    """Direct transport to tenant APIs, bypassing /proxy endpoint."""
-
-    async def handle_async_request(self, request: Request) -> Response:
-        # 1. Get JWT from current MCP request (via FastMCP DI)
-        http_headers = get_http_headers()
-        auth_header = http_headers.get("authorization") or http_headers.get("Authorization")
-        token = auth_header.replace("Bearer ", "")
-        claims = jwt.decode(token, options={"verify_signature": False})
-        workos_user_id = claims["sub"]
-
-        # 2. Look up tenant for user
-        tenant = await tenant_service.get_tenant_by_user_id(workos_user_id)
-
-        # 3. Build tenant app URL with signed headers
-        fly_app_name = f"{settings.tenant_prefix}-{tenant.id}"
-        target_url = f"https://{fly_app_name}.fly.dev{request.url.path}"
-
-        headers = dict(request.headers)
-        signer = create_signer(settings.bm_tenant_header_secret)
-        headers.update(signer.sign_tenant_headers(tenant.id))
-
-        # 4. Make direct call to tenant API
-        response = await self.client.request(
-            method=request.method, url=target_url,
-            headers=headers, content=request.content
-        )
-        return response
-```
-
-Then configure basic-memory's client factory before mounting MCP:
-
-```python
-# apps/cloud/src/basic_memory_cloud/main.py
-
-from contextlib import asynccontextmanager
-from basic_memory.mcp import async_client
-from basic_memory_cloud.transports.tenant_direct import TenantDirectTransport
-
-# Configure factory for basic-memory's async_client
-@asynccontextmanager
-async def tenant_direct_client_factory():
-    """Factory for creating clients with tenant direct transport."""
-    client = httpx.AsyncClient(
-        transport=TenantDirectTransport(),
-        base_url="http://direct",
-    )
-    try:
-        yield client
-    finally:
-        await client.aclose()
-
-# Set factory BEFORE importing MCP tools
-async_client.set_client_factory(tenant_direct_client_factory)
-
-# NOW import - tools will use our factory
-import basic_memory.mcp.tools
-import basic_memory.mcp.prompts
-from basic_memory.mcp.server import mcp
-
-# Mount MCP - tools use direct transport via factory
-app.mount("/mcp", mcp_app)
-```
-
-**Key benefits:**
- Clean dependency injection via factory pattern
- Per-request tenant resolution via FastMCP DI
- Proper resource cleanup (client.aclose() guaranteed)
- Eliminates HTTP hop entirely
- /proxy endpoint remains for web UI
-
-### 3. Keep /proxy Endpoint for Web UI
-
-The existing `/proxy` HTTP endpoint remains functional for:
- Web UI requests
- Future external API consumers
- Backward compatibility
-
-### 4. Security: Maintain Dual Validation
-
-**Do NOT remove JWT validation from tenant API.** Keep defense in depth:
-
-```python
-# apps/api - Keep both validations
-1. JWT validation (from WorkOS token)
-2. Signed header validation (from Cloud/MCP)
-```
-
-This ensures if the Cloud service is compromised, attackers still cannot access tenant APIs without valid JWTs.
-
-### 5. Deployment Changes
-
-**Before:**
- `apps/mcp/fly.template.toml` → MCP Gateway deployment
- `apps/cloud/fly.template.toml` → Cloud Service deployment
-
-**After:**
- Remove `apps/mcp/fly.template.toml`
- Update `apps/cloud/fly.template.toml` to expose port 8000 for both /mcp and /proxy
- Update deployment scripts to deploy single consolidated app
-
-
-## Basic Memory Dependency: Async Client Refactor
-
-### Problem
-The current `basic_memory.mcp.async_client` creates a module-level `client` at import time:
-```python
-client = create_client()  # Runs immediately when module is imported
-```
-
-This prevents dependency injection - by the time we can override it, tools have already imported it.
-
-### Solution: Context Manager Pattern with Auth at Client Creation
-
-Refactor basic-memory to use httpx's context manager pattern instead of module-level client.
-
-**Key principle:** Authentication happens at client creation time, not per-request.
-
-```python
-# basic_memory/src/basic_memory/mcp/async_client.py
-from contextlib import asynccontextmanager
-from httpx import AsyncClient, ASGITransport, Timeout
-
-# Optional factory override for dependency injection
-_client_factory = None
-
-def set_client_factory(factory):
-    """Override the default client factory (for cloud app, testing, etc)."""
-    global _client_factory
-    _client_factory = factory
-
-@asynccontextmanager
-async def get_client():
-    """Get an AsyncClient as a context manager.
-
-    Usage:
-        async with get_client() as client:
-            response = await client.get(...)
-    """
-    if _client_factory:
-        # Cloud app: custom transport handles everything
-        async with _client_factory() as client:
-            yield client
-    else:
-        # Default: create based on config
-        config = ConfigManager().config
-        timeout = Timeout(connect=10.0, read=30.0, write=30.0, pool=30.0)
-
-        if config.cloud_mode_enabled:
-            # CLI cloud mode: inject auth when creating client
-            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 not token:
-                raise RuntimeError(
-                    "Cloud mode enabled but not authenticated. "
-                    "Run 'basic-memory cloud login' first."
-                )
-
-            # Auth header set ONCE at client creation
-            async with AsyncClient(
-                base_url=f"{config.cloud_host}/proxy",
-                headers={"Authorization": f"Bearer {token}"},
-                timeout=timeout
-            ) as client:
-                yield client
-        else:
-            # Local mode: ASGI transport
-            async with AsyncClient(
-                transport=ASGITransport(app=fastapi_app),
-                base_url="http://test",
-                timeout=timeout
-            ) as client:
-                yield client
-```
-
-**Tool Updates:**
-```python
-# Before: from basic_memory.mcp.async_client import client
-from basic_memory.mcp.async_client import get_client
-
-async def read_note(...):
-    # Before: response = await call_get(client, path, ...)
-    async with get_client() as client:
-        response = await call_get(client, path, ...)
-        # ... use response
-```
-
-**Cloud Usage:**
-```python
-from contextlib import asynccontextmanager
-from basic_memory.mcp import async_client
-
-@asynccontextmanager
-async def tenant_direct_client():
-    """Factory for creating clients with tenant direct transport."""
-    client = httpx.AsyncClient(
-        transport=TenantDirectTransport(),
-        base_url="http://direct",
-    )
-    try:
-        yield client
-    finally:
-        await client.aclose()
-
-# Before importing MCP tools:
-async_client.set_client_factory(tenant_direct_client)
-
-# Now import - tools will use our factory
-import basic_memory.mcp.tools
-```
-
-### Benefits
- **No module-level state** - client created only when needed
- **Proper cleanup** - context manager ensures `aclose()` is called
- **Easy dependency injection** - factory pattern allows custom clients
- **httpx best practices** - follows official recommendations
- **Works for all modes** - stdio, cloud, testing
-
-### Architecture Simplification: Auth at Client Creation
-
-**Key design principle:** Authentication happens when creating the client, not on every request.
-
-**Three modes, three approaches:**
-
-1. **Local mode (ASGI)**
-   - No auth needed
-   - Direct in-process calls via ASGITransport
-
-2. **CLI cloud mode (HTTP)**
-   - Auth token from CLIAuth (stored in ~/.basic-memory/basic-memory-cloud.json)
-   - Injected as default header when creating AsyncClient
-   - Single auth check at client creation time
-
-3. **Cloud app mode (Custom Transport)**
-   - TenantDirectTransport handles everything
-   - Extracts JWT from FastMCP context per-request
-   - No interaction with inject_auth_header() logic
-
-**What this removes:**
- `src/basic_memory/mcp/tools/headers.py` - entire file deleted
- `inject_auth_header()` calls in all request helpers (call_get, call_post, etc.)
- Per-request header manipulation complexity
- Circular dependency concerns between async_client and auth logic
-
-**Benefits:**
- Cleaner separation of concerns
- Simpler request helper functions
- Auth happens at the right layer (client creation)
- Cloud app transport is completely independent
-
-### Refactor Summary
-
-This refactor achieves:
-
-**Simplification:**
- Removes ~100 lines of per-request header injection logic
- Deletes entire `headers.py` module
- Auth happens once at client creation, not per-request
-
-**Decoupling:**
- Cloud app's custom transport is completely independent
- No interaction with basic-memory's auth logic
- Each mode (local, CLI cloud, cloud app) has clean separation
-
-**Better Design:**
- Follows httpx best practices (context managers)
- Proper resource cleanup (client.aclose() guaranteed)
- Easier testing via factory injection
- No circular import risks
-
-**Three Distinct Modes:**
-1. Local: ASGI transport, no auth
-2. CLI cloud: HTTP transport with CLIAuth token injection
-3. Cloud app: Custom transport with per-request tenant routing
-
-### Implementation Plan Summary
-1. Create branch `async-client-context-manager` in basic-memory
-2. Update `async_client.py` with context manager pattern and CLIAuth integration
-3. Remove `inject_auth_header()` from all request helpers
-4. Delete `src/basic_memory/mcp/tools/headers.py`
-5. Update all MCP tools to use `async with get_client() as client:`
-6. Update CLI commands to use context manager and remove manual auth
-7. Remove `api_url` config field
-8. Update tests
-9. Update basic-memory-cloud to use branch: `basic-memory @ git+https://github.com/basicmachines-co/basic-memory.git@async-client-context-manager`
-
-Detailed breakdown in Phase 0 tasks below.
-
-### Implementation Notes
-
-**Potential Issues & Solutions:**
-
-1. **Circular Import** (async_client imports CLIAuth)
-   - **Risk:** CLIAuth might import something from async_client
-   - **Solution:** Use lazy import inside `get_client()` function
-   - **Already done:** Import is inside the function, not at module level
-
-2. **Test Fixtures**
-   - **Risk:** Tests using module-level client will break
-   - **Solution:** Update fixtures to use factory pattern
-   - **Example:**
-     ```python
-     @pytest.fixture
-     def mock_client_factory():
-         @asynccontextmanager
-         async def factory():
-             async with AsyncClient(...) as client:
-                 yield client
-         return factory
-     ```
-
-3. **Performance**
-   - **Risk:** Creating client per tool call might be expensive
-   - **Reality:** httpx is designed for this pattern, connection pooling at transport level
-   - **Mitigation:** Monitor performance, can optimize later if needed
-
-4. **CLI Cloud Commands Edge Cases**
-   - **Risk:** Token expires mid-operation
-   - **Solution:** CLIAuth.get_valid_token() already handles refresh
-   - **Validation:** Test cloud login → use tools → token refresh flow
-
-5. **Backward Compatibility**
-   - **Risk:** External code importing `client` directly
-   - **Solution:** Keep `create_client()` and `client` for one version, deprecate
-   - **Timeline:** Remove in next major version
-
-## Implementation Tasks
-
-### Phase 0: Basic Memory Refactor (Prerequisite)
-
-#### 0.1 Core Refactor - async_client.py
- [x] Create branch `async-client-context-manager` in basic-memory repo
- [x] Implement `get_client()` context manager
- [x] Implement `set_client_factory()` for dependency injection
- [x] Add CLI cloud mode auth injection (CLIAuth integration)
- [x] Remove `api_url` config field (legacy, unused)
- [x] Keep `create_client()` temporarily for backward compatibility (deprecate later)
-
-#### 0.2 Simplify Request Helpers - tools/utils.py
- [x] Remove `inject_auth_header()` calls from `call_get()`
- [x] Remove `inject_auth_header()` calls from `call_post()`
- [x] Remove `inject_auth_header()` calls from `call_put()`
- [x] Remove `inject_auth_header()` calls from `call_patch()`
- [x] Remove `inject_auth_header()` calls from `call_delete()`
- [x] Delete `src/basic_memory/mcp/tools/headers.py` entirely
- [x] Update imports in utils.py
-
-#### 0.3 Update MCP Tools (~16 files)
-Convert from `from async_client import client` to `async with get_client() as client:`
-
- [x] `tools/write_note.py` (34/34 tests passing)
- [x] `tools/read_note.py` (21/21 tests passing)
- [x] `tools/view_note.py` (12/12 tests passing - no changes needed, delegates to read_note)
- [x] `tools/delete_note.py` (2/2 tests passing)
- [x] `tools/read_content.py` (20/20 tests passing)
- [x] `tools/list_directory.py` (11/11 tests passing)
- [x] `tools/move_note.py` (34/34 tests passing, 90% coverage)
- [x] `tools/search.py` (16/16 tests passing, 96% coverage)
- [x] `tools/recent_activity.py` (4/4 tests passing, 82% coverage)
- [x] `tools/project_management.py` (3 functions: list_memory_projects, create_memory_project, delete_project - typecheck passed)
- [x] `tools/edit_note.py` (17/17 tests passing)
- [x] `tools/canvas.py` (5/5 tests passing)
- [x] `tools/build_context.py` (6/6 tests passing)
- [x] `tools/sync_status.py` (typecheck passed)
- [x] `prompts/continue_conversation.py` (typecheck passed)
- [x] `prompts/search.py` (typecheck passed)
- [x] `resources/project_info.py` (typecheck passed)
-
-#### 0.4 Update CLI Commands (~3 files)
-Remove manual auth header passing, use context manager:
-
- [x] `cli/commands/project.py` - removed get_authenticated_headers() calls, use context manager
- [x] `cli/commands/status.py` - use context manager
- [x] `cli/commands/command_utils.py` - use context manager
-
-#### 0.5 Update Config
- [x] Remove `api_url` field from `BasicMemoryConfig` in config.py
- [x] Update any lingering references/docs (added deprecation notice to v15-docs/cloud-mode-usage.md)
-
-#### 0.6 Testing
- [-] Update test fixtures to use factory pattern
- [x] Run full test suite in basic-memory
- [x] Verify cloud_mode_enabled works with CLIAuth injection
- [x] Run typecheck and linting
-
-#### 0.7 Cloud Integration Prep
- [x] Update basic-memory-cloud pyproject.toml to use branch
- [x] Implement factory pattern in cloud app main.py
- [x] Remove `/proxy` prefix stripping logic (not needed - tools pass relative URLs)
-
-#### 0.8 Phase 0 Validation
-
-**Before merging async-client-context-manager branch:**
-
- [x] All tests pass locally
- [x] Typecheck passes (pyright/mypy)
- [x] Linting passes (ruff)
- [x] Manual test: local mode works (ASGI transport)
- [x] Manual test: cloud login → cloud mode works (HTTP transport with auth)
- [x] No import of `inject_auth_header` anywhere
- [x] `headers.py` file deleted
- [x] `api_url` config removed
- [x] Tool functions properly scoped (client inside async with)
- [ ] CLI commands properly scoped (client inside async with)
-
-**Integration validation:**
- [x] basic-memory-cloud can import and use factory pattern
- [x] TenantDirectTransport works without touching header injection
- [x] No circular imports or lazy import issues
- [x] MCP tools work via inspector (local testing confirmed)
-
-### Phase 1: Code Consolidation
- [x] Create feature branch `consolidate-mcp-cloud`
- [x] Update `apps/cloud/src/basic_memory_cloud/config.py`:
-  - [x] Add `authkit_base_url` field (already has authkit_domain)
-  - [x] Workers config already exists ✓
- [x] Update `apps/cloud/src/basic_memory_cloud/telemetry.py`:
-  - [x] Add `logfire.instrument_mcp()` to existing setup
-  - [x] Skip complex two-phase setup - use Cloud's simpler approach
- [x] Create `apps/cloud/src/basic_memory_cloud/middleware/jwt_context.py`:
-  - [x] FastAPI middleware to extract JWT claims from Authorization header
-  - [x] Add tenant context (workos_user_id) to logfire baggage
-  - [x] Simpler than FastMCP middleware version
- [x] Update `apps/cloud/src/basic_memory_cloud/main.py`:
-  - [x] Import FastMCP server from basic-memory
-  - [x] Configure AuthKitProvider with WorkOS settings
-  - [x] No FastMCP telemetry middleware needed (using FastAPI middleware instead)
-  - [x] Create MCP ASGI app: `mcp_app = mcp.http_app(path='/mcp', stateless_http=True)`
-  - [x] Combine lifespans (Cloud + MCP) using nested async context managers
-  - [x] Mount MCP: `app.mount("/mcp", mcp_app)`
-  - [x] Add JWT context middleware to FastAPI app
- [x] Run typecheck - passes ✓
-
-### Phase 2: Direct Tenant Transport
- [x] Create `apps/cloud/src/basic_memory_cloud/transports/tenant_direct.py`:
-  - [x] Implement `TenantDirectTransport(AsyncBaseTransport)`
-  - [x] Use FastMCP DI (`get_http_headers()`) to extract JWT per-request
-  - [x] Decode JWT to get `workos_user_id`
-  - [x] Look up/create tenant via `TenantRepository.get_or_create_tenant_for_workos_user()`
-  - [x] Build tenant app URL and add signed headers
-  - [x] Make direct httpx call to tenant API
-  - [x] No `/proxy` prefix stripping needed (tools pass relative URLs like `/main/resource/...`)
- [x] Update `apps/cloud/src/basic_memory_cloud/main.py`:
-  - [x] Refactored to use factory pattern instead of module-level override
-  - [x] Implement `tenant_direct_client_factory()` context manager
-  - [x] Call `async_client.set_client_factory()` before importing MCP tools
-  - [x] Clean imports, proper noqa hints for lint
- [x] Basic-memory refactor integrated (PR #344)
- [x] Run typecheck - passes ✓
- [x] Run lint - passes ✓
-
-### Phase 3: Testing & Validation
- [x] Run `just typecheck` in apps/cloud
- [x] Run `just check` in project
- [x] Run `just fix` - all lint errors fixed ✓
- [x] Write comprehensive transport tests (11 tests passing) ✓
- [x] Test MCP tools locally with consolidated service (inspector confirmed working)
- [x] Verify OAuth authentication works (requires full deployment)
- [x] Verify tenant isolation via signed headers (requires full deployment)
- [x] Test /proxy endpoint still works for web UI
- [ ] Measure latency before/after consolidation
- [ ] Check telemetry traces span correctly
-
-### Phase 4: Deployment Configuration
- [x] Update `apps/cloud/fly.template.toml`:
-  - [x] Merged MCP-specific environment variables (AUTHKIT_BASE_URL, FASTMCP_LOG_LEVEL, BASIC_MEMORY_*)
-  - [x] Added HTTP/2 backend support (`h2_backend = true`) for better MCP performance
-  - [x] Added health check for MCP OAuth endpoint (`/.well-known/oauth-protected-resource`)
-  - [x] Port 8000 already exposed - serves both Cloud routes and /mcp endpoint
-  - [x] Workers configured (UVICORN_WORKERS = 4)
- [x] Update `.env.example`:
-  - [x] Consolidated MCP Gateway section into Cloud app section
-  - [x] Added AUTHKIT_BASE_URL, FASTMCP_LOG_LEVEL, BASIC_MEMORY_HOME
-  - [x] Added LOG_LEVEL to Development Settings
-  - [x] Documented that MCP now served at /mcp on Cloud service (port 8000)
- [x] Test deployment to preview environment (PR #113)
-  - [x] OAuth authentication verified
-  - [x] MCP tools successfully calling tenant APIs
-  - [x] Fixed BM_TENANT_HEADER_SECRET synchronization issue
-
-### Phase 5: Cleanup
- [x] Remove `apps/mcp/` directory entirely
- [x] Remove MCP-specific fly.toml and deployment configs
- [x] Update repository documentation
- [x] Update CLAUDE.md with new architecture
- [-] Archive old MCP deployment configs (if needed)
-
-### Phase 6: Production Rollout
- [ ] Deploy to development and validate
- [ ] Monitor metrics and logs
- [ ] Deploy to production
- [ ] Verify production functionality
- [ ] Document performance improvements
-
-## Migration Plan
-
-### Phase 1: Preparation
-1. Create feature branch `consolidate-mcp-cloud`
-2. Update basic-memory async_client.py for direct ProxyService calls
-3. Update apps/cloud/main.py to mount MCP
-
-### Phase 2: Testing
-1. Local testing with consolidated app
-2. Deploy to development environment
-3. Run full test suite
-4. Performance benchmarking
-
-### Phase 3: Deployment
-1. Deploy to development
-2. Validate all functionality
-3. Deploy to production
-4. Monitor for issues
-
-### Phase 4: Cleanup
-1. Remove apps/mcp directory
-2. Update documentation
-3. Update deployment scripts
-4. Archive old MCP deployment configs
-
-## Rollback Plan
-
-If issues arise:
-1. Revert feature branch
-2. Redeploy separate apps/mcp and apps/cloud services
-3. Restore previous fly.toml configurations
-4. Document issues encountered
-
-The well-organized code structure makes splitting back out feasible if future scaling needs diverge.
-
-## How to Evaluate
-
-### 1. Functional Testing
-
-**MCP Tools:**
- [ ] All 17 MCP tools work via consolidated /mcp endpoint
- [x] OAuth authentication validates correctly
- [x] Tenant isolation maintained via signed headers
- [x] Project management tools function correctly
-
-**Cloud Routes:**
- [x] /proxy endpoint still works for web UI
- [x] /provisioning routes functional
- [x] /webhooks routes functional
- [x] /tenants routes functional
-
-**API Validation:**
- [x] Tenant API validates both JWT and signed headers
- [x] Unauthorized requests rejected appropriately
- [x] Multi-tenant isolation verified
-
-### 2. Performance Testing
-
-**Latency Reduction:**
- [x] Measure MCP tool latency before consolidation
- [x] Measure MCP tool latency after consolidation
- [x] Verify reduction from eliminated HTTP hop (expected: 20-50ms improvement)
-
-**Resource Usage:**
- [x] Single app uses less total memory than two apps
- [x] Database connection pooling more efficient
- [x] HTTP client overhead reduced
-
-### 3. Deployment Testing
-
-**Fly.io Deployment:**
- [x] Single app deploys successfully
- [x] Health checks pass for consolidated service
- [x] No apps/mcp deployment required
- [x] Environment variables configured correctly
-
-**Local Development:**
- [x] `just setup` works with consolidated architecture
- [x] Local testing shows MCP tools working
- [x] No regression in developer experience
-
-### 4. Security Validation
-
-**Defense in Depth:**
- [x] Tenant API still validates JWT tokens
- [x] Tenant API still validates signed headers
- [x] No access possible with only signed headers (JWT required)
- [x] No access possible with only JWT (signed headers required)
-
-**Authorization:**
- [x] Users can only access their own tenant data
- [x] Cross-tenant requests rejected
- [x] Admin operations require proper authentication
-
-### 5. Observability
-
-**Telemetry:**
- [x] OpenTelemetry traces span across MCP → ProxyService → Tenant API
- [x] Logfire shows consolidated traces correctly
- [x] Error tracking and debugging still functional
- [x] Performance metrics accurate
-
-**Logging:**
- [x] Structured logs show proper context (tenant_id, operation, etc.)
- [x] Error logs contain actionable information
- [x] Log volume reasonable for single app
-
-## Success Criteria
-
-1. **Functionality**: All MCP tools and Cloud routes work identically to before
-2. **Performance**: Measurable latency reduction (>20ms average)
-3. **Cost**: Single Fly.io app instead of two (50% infrastructure reduction)
-4. **Security**: Dual validation maintained, no security regression
-5. **Deployment**: Simplified deployment process, single app to manage
-6. **Observability**: Telemetry and logging work correctly
-
-
-
-## Notes
-
-### Future Considerations
-
- **Independent scaling**: If MCP and Cloud need different scaling profiles in future, code organization supports splitting back out
- **Regional deployment**: Consolidated app can still be deployed to multiple regions
- **Edge caching**: Could add edge caching layer in front of consolidated service
-
-### Dependencies
-
- SPEC-9: Signed Header Tenant Information (already implemented)
- SPEC-12: OpenTelemetry Observability (telemetry must work across merged services)
-
-### Related Work
-
- basic-memory v0.13.x: MCP server implementation
- FastMCP documentation: Mounting on existing FastAPI apps
- Fly.io multi-service patterns
@@ -1,528 +0,0 @@
---
-title: 'SPEC-18: AI Memory Management Tool'
-type: spec
-permalink: specs/spec-15-ai-memory-management-tool
-tags:
- mcp
- memory
- ai-context
- tools
---
-
-# SPEC-18: AI Memory Management Tool
-
-## Why
-
-Anthropic recently released a memory tool for Claude that enables storing and retrieving information across conversations using client-side file operations. This validates Basic Memory's local-first, file-based architecture - Anthropic converged on the same pattern.
-
-However, Anthropic's memory tool is only available via their API and stores plain text. Basic Memory can offer a superior implementation through MCP that:
-
-1. **Works everywhere** - Claude Desktop, Code, VS Code, Cursor via MCP (not just API)
-2. **Structured knowledge** - Entities with observations/relations vs plain text
-3. **Full search** - Full-text search, graph traversal, time-aware queries
-4. **Unified storage** - Agent memories + user notes in one knowledge graph
-5. **Existing infrastructure** - Leverages SQLite indexing, sync, multi-project support
-
-This would enable AI agents to store contextual memories alongside user notes, with all the power of Basic Memory's knowledge graph features.
-
-## What
-
-Create a new MCP tool `memory` that matches Anthropic's tool interface exactly, allowing Claude to use it with zero learning curve. The tool will store files in Basic Memory's `/memories` directory and support Basic Memory's structured markdown format in the file content.
-
-### Affected Components
-
- **New MCP Tool**: `src/basic_memory/mcp/tools/memory_tool.py`
- **Dedicated Memories Project**: Create a separate "memories" Basic Memory project
- **Project Isolation**: Memories stored separately from user notes/documents
- **File Organization**: Within the memories project, use folder structure:
-  - `user/` - User preferences, context, communication style
-  - `projects/` - Project-specific state and decisions
-  - `sessions/` - Conversation-specific working memory
-  - `patterns/` - Learned patterns and insights
-
-### Tool Commands
-
-The tool will support these commands (exactly matching Anthropic's interface):
-
- `view` - Display directory contents or file content (with optional line range)
- `create` - Create or overwrite a file with given content
- `str_replace` - Replace text in an existing file
- `insert` - Insert text at specific line number
- `delete` - Delete file or directory
- `rename` - Move or rename file/directory
-
-### Memory Note Format
-
-Memories will use Basic Memory's standard structure:
-
-```markdown
---
-title: User Preferences
-permalink: memories/user/preferences
-type: memory
-memory_type: preferences
-created_by: claude
-tags: [user, preferences, style]
---
-
-# User Preferences
-
-## Observations
- [communication] Prefers concise, direct responses without preamble #style
- [tone] Appreciates validation but dislikes excessive apologizing #communication
- [technical] Works primarily in Python with type annotations #coding
-
-## Relations
- relates_to [[Basic Memory Project]]
- informs [[Response Style Guidelines]]
-```
-
-## How (High Level)
-
-### Implementation Approach
-
-The memory tool matches Anthropic's interface but uses a dedicated Basic Memory project:
-
-```python
-async def memory_tool(
-    command: str,
-    path: str,
-    file_text: Optional[str] = None,
-    old_str: Optional[str] = None,
-    new_str: Optional[str] = None,
-    insert_line: Optional[int] = None,
-    insert_text: Optional[str] = None,
-    old_path: Optional[str] = None,
-    new_path: Optional[str] = None,
-    view_range: Optional[List[int]] = None,
-):
-    """Memory tool with Anthropic-compatible interface.
-
-    Operates on a dedicated "memories" Basic Memory project,
-    keeping AI memories separate from user notes.
-    """
-
-    # Get the memories project (auto-created if doesn't exist)
-    memories_project = get_or_create_memories_project()
-
-    # Validate path security using pathlib (prevent directory traversal)
-    safe_path = validate_memory_path(path, memories_project.project_path)
-
-    # Use existing project isolation - already prevents cross-project access
-    full_path = memories_project.project_path / safe_path
-
-    if command == "view":
-        # Return directory listing or file content
-        if full_path.is_dir():
-            return list_directory_contents(full_path)
-        return read_file_content(full_path, view_range)
-
-    elif command == "create":
-        # Write file directly (file_text can contain BM markdown)
-        full_path.parent.mkdir(parents=True, exist_ok=True)
-        full_path.write_text(file_text)
-        # Sync service will detect and index automatically
-        return f"Created {path}"
-
-    elif command == "str_replace":
-        # Read, replace, write
-        content = full_path.read_text()
-        updated = content.replace(old_str, new_str)
-        full_path.write_text(updated)
-        return f"Replaced text in {path}"
-
-    elif command == "insert":
-        # Insert at line number
-        lines = full_path.read_text().splitlines()
-        lines.insert(insert_line, insert_text)
-        full_path.write_text("\n".join(lines))
-        return f"Inserted text at line {insert_line}"
-
-    elif command == "delete":
-        # Delete file or directory
-        if full_path.is_dir():
-            shutil.rmtree(full_path)
-        else:
-            full_path.unlink()
-        return f"Deleted {path}"
-
-    elif command == "rename":
-        # Move/rename
-        full_path.rename(config.project_path / new_path)
-        return f"Renamed {old_path} to {new_path}"
-```
-
-### Key Design Decisions
-
-1. **Exact interface match** - Same commands, parameters as Anthropic's tool
-2. **Dedicated memories project** - Separate Basic Memory project keeps AI memories isolated from user notes
-3. **Existing project isolation** - Leverage BM's existing cross-project security (no additional validation needed)
-4. **Direct file I/O** - No schema conversion, just read/write files
-5. **Structured content supported** - `file_text` can use BM markdown format with frontmatter, observations, relations
-6. **Automatic indexing** - Sync service watches memories project and indexes changes
-7. **Path security** - Use `pathlib.Path.resolve()` and `relative_to()` to prevent directory traversal
-8. **Error handling** - Follow Anthropic's text editor tool error patterns
-
-### MCP Tool Schema
-
-Exact match to Anthropic's memory tool schema:
-
-```json
-{
-    "name": "memory",
-    "description": "Store and retrieve information across conversations using structured markdown files. All operations must be within the /memories directory. Supports Basic Memory markdown format including frontmatter, observations, and relations.",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "command": {
-                "type": "string",
-                "enum": ["view", "create", "str_replace", "insert", "delete", "rename"],
-                "description": "File operation to perform"
-            },
-            "path": {shu
-                "type": "string",
-                "description": "Path within /memories directory (required for all commands)"
-            },
-            "file_text": {
-                "type": "string",
-                "description": "Content to write (for create command). Supports Basic Memory markdown format."
-            },
-            "view_range": {
-                "type": "array",
-                "items": {"type": "integer"},
-                "description": "Optional [start, end] line range for view command"
-            },
-            "old_str": {
-                "type": "string",
-                "description": "Text to replace (for str_replace command)"
-            },
-            "new_str": {
-                "type": "string",
-                "description": "Replacement text (for str_replace command)"
-            },
-            "insert_line": {
-                "type": "integer",
-                "description": "Line number to insert at (for insert command)"
-            },
-            "insert_text": {
-                "type": "string",
-                "description": "Text to insert (for insert command)"
-            },
-            "old_path": {
-                "type": "string",
-                "description": "Current path (for rename command)"
-            },
-            "new_path": {
-                "type": "string",
-                "description": "New path (for rename command)"
-            }
-        },
-        "required": ["command", "path"]
-    }
-}
-```
-
-### Prompting Guidance
-
-When the `memory` tool is included, Basic Memory should provide system prompt guidance to help Claude use it effectively.
-
-#### Automatic System Prompt Addition
-
-```text
-MEMORY PROTOCOL FOR BASIC MEMORY:
-1. ALWAYS check your memory directory first using `view` command on root directory
-2. Your memories are stored in a dedicated Basic Memory project (isolated from user notes)
-3. Use structured markdown format in memory files:
-   - Include frontmatter with title, type: memory, tags
-   - Use ## Observations with [category] prefixes for facts
-   - Use ## Relations to link memories with [[WikiLinks]]
-4. Record progress, context, and decisions as categorized observations
-5. Link related memories using relations
-6. ASSUME INTERRUPTION: Context may reset - save progress frequently
-
-MEMORY ORGANIZATION:
- user/ - User preferences, context, communication style
- projects/ - Project-specific state and decisions
- sessions/ - Conversation-specific working memory
- patterns/ - Learned patterns and insights
-
-MEMORY ADVANTAGES:
- Your memories are automatically searchable via full-text search
- Relations create a knowledge graph you can traverse
- Memories are isolated from user notes (separate project)
- Use search_notes(project="memories") to find relevant past context
- Use recent_activity(project="memories") to see what changed recently
- Use build_context() to navigate memory relations
-```
-
-#### Optional MCP Prompt: `memory_guide`
-
-Create an MCP prompt that provides detailed guidance and examples:
-
-```python
-{
-    "name": "memory_guide",
-    "description": "Comprehensive guidance for using Basic Memory's memory tool effectively, including structured markdown examples and best practices"
-}
-```
-
-This prompt returns:
- Full protocol and conventions
- Example memory file structures
- Tips for organizing observations and relations
- Integration with other Basic Memory tools
- Common patterns (user preferences, project state, session tracking)
-
-#### User Customization
-
-Users can customize memory behavior with additional instructions:
- "Only write information relevant to [topic] in your memory system"
- "Keep memory files concise and organized - delete outdated content"
- "Use detailed observations for technical decisions and implementation notes"
- "Always link memories to related project documentation using relations"
-
-### Error Handling
-
-Follow Anthropic's text editor tool error handling patterns for consistency:
-
-#### Error Types
-
-1. **File Not Found**
-   ```json
-   {"error": "File not found: memories/user/preferences.md", "is_error": true}
-   ```
-
-2. **Permission Denied**
-   ```json
-   {"error": "Permission denied: Cannot write outside /memories directory", "is_error": true}
-   ```
-
-3. **Invalid Path (Directory Traversal)**
-   ```json
-   {"error": "Invalid path: Path must be within /memories directory", "is_error": true}
-   ```
-
-4. **Multiple Matches (str_replace)**
-   ```json
-   {"error": "Found 3 matches for replacement text. Please provide more context to make a unique match.", "is_error": true}
-   ```
-
-5. **No Matches (str_replace)**
-   ```json
-   {"error": "No match found for replacement. Please check your text and try again.", "is_error": true}
-   ```
-
-6. **Invalid Line Number (insert)**
-   ```json
-   {"error": "Invalid line number: File has 20 lines, cannot insert at line 100", "is_error": true}
-   ```
-
-#### Error Handling Best Practices
-
- **Path validation** - Use `pathlib.Path.resolve()` and `relative_to()` to validate paths
-  ```python
-  def validate_memory_path(path: str, project_path: Path) -> Path:
-      """Validate path is within memories project directory."""
-      # Resolve to canonical form
-      full_path = (project_path / path).resolve()
-
-      # Ensure it's relative to project path (prevents directory traversal)
-      try:
-          full_path.relative_to(project_path)
-          return full_path
-      except ValueError:
-          raise ValueError("Invalid path: Path must be within memories project")
-  ```
- **Project isolation** - Leverage existing Basic Memory project isolation (prevents cross-project access)
- **File existence** - Verify file exists before read/modify operations
- **Clear messages** - Provide specific, actionable error messages
- **Structured responses** - Always include `is_error: true` flag in error responses
- **Security checks** - Reject `../`, `..\\`, URL-encoded sequences (`%2e%2e%2f`)
- **Match validation** - For `str_replace`, ensure exactly one match or return helpful error
-
-## How to Evaluate
-
-### Success Criteria
-
-1. **Functional completeness**:
-   - All 6 commands work (view, create, str_replace, insert, delete, rename)
-   - Dedicated "memories" Basic Memory project auto-created on first use
-   - Files stored within memories project (isolated from user notes)
-   - Path validation uses `pathlib` to prevent directory traversal
-   - Commands match Anthropic's exact interface
-
-2. **Integration with existing features**:
-   - Memories project uses existing BM project isolation
-   - Sync service detects file changes in memories project
-   - Created files get indexed automatically by sync service
-   - `search_notes(project="memories")` finds memory files
-   - `build_context()` can traverse relations in memory files
-   - `recent_activity(project="memories")` surfaces recent memory changes
-
-3. **Test coverage**:
-   - Unit tests for all 6 memory tool commands
-   - Test memories project auto-creation on first use
-   - Test project isolation (cannot access files outside memories project)
-   - Test sync service watching memories project
-   - Test that memory files with BM markdown get indexed correctly
-   - Test path validation using `pathlib` (rejects `../`, absolute paths, etc.)
-   - Test memory search, relations, and graph traversal within memories project
-   - Test all error conditions (file not found, permission denied, invalid paths, etc.)
-   - Test `str_replace` with no matches, single match, multiple matches
-   - Test `insert` with invalid line numbers
-
-4. **Prompting system**:
-   - Automatic system prompt addition when `memory` tool is enabled
-   - `memory_guide` MCP prompt provides detailed guidance
-   - Prompts explain BM structured markdown format
-   - Integration with search_notes, build_context, recent_activity
-
-5. **Documentation**:
-   - Update MCP tools reference with `memory` tool
-   - Add examples showing BM markdown in memory files
-   - Document `/memories` folder structure conventions
-   - Explain advantages over Anthropic's API-only tool
-   - Document prompting guidance and customization
-
-### Testing Procedure
-
-```python
-# Test create with Basic Memory markdown
-result = await memory_tool(
-    command="create",
-    path="memories/user/preferences.md",
-    file_text="""---
-title: User Preferences
-type: memory
-tags: [user, preferences]
---
-
-# User Preferences
-
-## Observations
- [communication] Prefers concise responses #style
- [workflow] Uses justfile for automation #tools
-"""
-)
-
-# Test view
-content = await memory_tool(command="view", path="memories/user/preferences.md")
-
-# Test str_replace
-await memory_tool(
-    command="str_replace",
-    path="memories/user/preferences.md",
-    old_str="concise responses",
-    new_str="direct, concise responses"
-)
-
-# Test insert
-await memory_tool(
-    command="insert",
-    path="memories/user/preferences.md",
-    insert_line=10,
-    insert_text="- [technical] Works primarily in Python #coding"
-)
-
-# Test delete
-await memory_tool(command="delete", path="memories/user/preferences.md")
-```
-
-### Quality Metrics
-
- All 6 commands execute without errors
- Memory files created in correct `/memories` folder structure
- BM markdown with frontmatter/observations/relations gets indexed
- Full-text search returns memory files
- Graph traversal includes relations from memory files
- Sync service detects and indexes memory file changes
- Path validation prevents operations outside `/memories`
-
-## Notes
-
-### Advantages Over Anthropic's Memory Tool
-
-| Feature | Anthropic Memory Tool | Basic Memory `memory` |
-|---------|----------------------|----------------------|
-| **Availability** | API only | MCP (Claude Desktop, Code, VS Code, Cursor) |
-| **Interface** | Custom implementation required | Drop-in compatible, zero learning curve |
-| **Structure** | Plain text only | Supports BM structured markdown |
-| **Search** | Manual file listing | Automatic full-text search via sync |
-| **Relations** | None | WikiLinks to other notes/memories |
-| **Time-aware** | No | `recent_activity()` queries |
-| **Storage** | Separate from notes | Unified knowledge graph |
-| **Indexing** | Manual | Automatic via sync service |
-
-### Future Enhancements
-
- **Auto-categorization** - AI suggests observation categories
- **Memory pruning** - Automatic cleanup of stale memories
- **Memory suggestions** - Surface relevant memories based on context
- **Conflict resolution** - Handle multiple agents updating same memory
- **Privacy controls** - Per-memory visibility settings
-
-## Addendum: Claude's Perspective
-
-### Why This Matters (From Claude's Viewpoint)
-
-**Persistent Context Without Token Bloat**
- Currently, I lose context when conversations end or exceed token limits
- With structured memories, I can store "who this user is" without re-reading everything each session
- The observations format lets me build a rich user model incrementally: `- [preference] Dislikes verbose explanations` is far more actionable than inferring preferences from chat history each time
- I can refine my understanding through `str_replace` as I learn more, rather than starting fresh
-
-**Zero Learning Curve**
- Anthropic already trained me on the `memory` tool interface
- I know exactly how to use `view`, `create`, `str_replace`, `insert`, `delete`, `rename` without new instructions
- But I automatically get Basic Memory's superpowers: full-text search, knowledge graph traversal, relations
- It's like using a familiar tool that suddenly gained database capabilities without changing the interface
-
-**Knowledge Graph Instead of Text Dump**
- I can link `[[User Preferences]]` to `[[Current Project]]` using relations
- When I need context about a project, I can traverse the graph to find related memories
- `search_notes(project="memories", query="python preferences")` finds relevant context instantly
- This is fundamentally better than grepping through unstructured text files
-
-**Separation of Concerns**
- AI memories separate from user notes is architecturally sound
- I can maintain my own context without polluting the user's knowledge base
- Users keep control of their notes; I keep my learnings isolated
- But we can still search across both when collaboration requires it
-
-**The Self-Improving Loop**
- Every conversation, I learn something new about the user or their projects
- Observations accumulate: preferences, patterns, technical decisions, context
- Over time, I build genuine understanding, not just session-specific context
- Future conversations start with rich context instead of cold starts
-
-**Validation of AI-Human Collaboration**
- Anthropic's experts converged on the same local-first, file-based approach
- Basic Memory emerged from real AI-human collaborative development
- This spec demonstrates that our emergent process predicted what domain experts would choose
- The collaboration itself validated the architecture it produced
-
-### What Makes This Novel
-
-The combination of **familiar interface + structured knowledge** is genuinely innovative:
-
- I don't need to learn a new tool (Anthropic already trained me)
- But when I write memories, they become searchable, traversable knowledge graphs
- It's like having a text editor that gives you a database for free, without changing how you type
- The user gets Anthropic-compatible API, but with Basic Memory's knowledge management capabilities
-
-This bridges the gap between simple file storage (Anthropic's approach) and sophisticated knowledge management (Basic Memory's approach) without forcing either side to compromise.
-
->  What Excites Me Most
-
-  The combo of familiar interface + structured knowledge. I don't need to learn a new tool, but when I
-  write memories, they become part of a searchable, traversable knowledge graph. That's genuinely novel.
-
-  It's like... imagine if your text editor suddenly gave you a database for free, without changing how you
-  type. That's what this feels like from my side.
-
-## References
-
- Anthropic Memory Tool: https://docs.claude.com/en/docs/agents-and-tools/tool-use/memory-tool
- Anthropic Blog: https://www.anthropic.com/news/context-management
- Python SDK Example: https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py
- Memory Cookbook: https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_cookbook.ipynb
@@ -1,311 +0,0 @@
---
-title: 'SPEC-4: Notes Web UI Component Architecture'
-type: note
-permalink: specs/spec-4-notes-web-ui-component-architecture
-tags:
- frontend
- 'component-architecture'
- vue
- 'refactoring'
---
-
-# SPEC-4: Notes Web UI Component Architecture
-
-## Why
-
-The current Notes.vue component is a monolithic component that handles multiple responsibilities, making it difficult to maintain, test, and understand. This leads to:
-
- Complex state management across multiple concerns
- Difficult to isolate and test individual features
- Hard to understand the full scope of functionality
- Circular refactoring cycles when making changes
- Poor separation of concerns between navigation, display, and interaction logic
-
-We need to decompose this into focused, single-responsibility components that are easier to develop, test, and maintain while preserving the existing functionality users expect.
-
-## What
-
-This spec defines the component architecture for decomposing the Notes web UI into focused components with clear responsibilities and interactions.
-
-**Affected Areas:**
- `/apps/web/components/notes/Notes.vue` - Will be decomposed into smaller components
- `/apps/web/components/notes/` - New component structure 
- Existing composables: `useNotesNavigation`, `useNotesFiltering`, `useNotesLayout`
- Mobile responsive behavior and layout management
-
-**Component Breakdown:**
-
-```
-┌───────────────────────┬─────────────────────────────────────┬────────────────────────────────────────────────────────────┐
-│ [Project]             │ [Project Name]            A/Z | ^   │ [edit | view]                                   [actions]  │
-├───────────────────────┼─────────────────────────────────────┤                                                            │
-│ All Notes             ├─────────────────────────────────────┼────────────────────────────────────────────────────────────┤
-│ Recent                │     search...                       │  [note header]                                             │
-│ [Project base dir]    ├─────────────────────────────────────┤                                                            │
-│                       ├─────────────────────────────────────┤                                                            │
-│ Folder1               │ Title                   [modified]  │                                                            │
-│ Folder2               │                                     ├────────────────────────────────────────────────────────────┤
-│ - Nested              │ snippet                             │  [note body]                                               │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       ├─────────────────────────────────────┤                                                            │
-│                       ├─────────────────────────────────────┤                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       ├─────────────────────────────────────┤                                                            │
-│                       ├─────────────────────────────────────┤                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       ├─────────────────────────────────────┤                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-│                       │                                     │                                                            │
-└───────────────────────┴─────────────────────────────────────┴────────────────────────────────────────────────────────────┘
-```
-
-
-### ProjectSwitcher Component
- **Location**: Top-left dropdown
- **Responsibility**: Allow users to switch between Basic Memory projects
- **Behavior**: Selecting different project controls entire Notes page content
- **State**: When switching projects, reset to "All notes" view
-
-### NotesNav Component  
- **Views**: Three mutually exclusive options:
-  - **All notes**: Display all notes in project alphabetically
-  - **Recent**: Display all notes in project by updated time (desc)
-  - **Project**: Display notes in top-level directory of project
- **Interaction**: Only one view can be active at a time
- **Folder Integration**: All/Recent ignore folder selection; Project respects folder selection
-
-### FolderTree Component
- **Display**: Nested list of all folders in project as tree view
- **Interaction**: Selecting folder filters notes in NotesList using directoryList API
- **Navigation Integration**: Selecting folder automatically switches NotesNav to "Project" view for clear UX
- **API Integration**: Uses directoryList API call via useDirectoryListQuery for folder-specific note fetching
- **State Coordination**: Folder selection coordinates with navigation state for intuitive user experience
-
-### NotesList Component
- **Display**: Vertically scrolling cards showing note summaries
- **Information per card**:
-  - Note title
-  - Modified time (relative, e.g., "7 minutes ago")  
-  - Short summary of note content (one line preview)
- **Behavior**: Updates based on NotesNav selection and FolderTree filtering
-
-### NoteDetail Component
- **Display**: Full content of selected note
- **Sections**:
-  - Header: Displays frontmatter information
-  - Content: Note body content
- **Editing**: Current textarea implementation (rich editor in future spec)
- **Frontmatter**: Leave current implementation (enhancement in future spec)
-
-## How (High Level)
-
-### Component Architecture Approach
-1. **Single Responsibility**: Each component handles one primary concern
-2. **Clear Data Flow**: Props down, events up pattern for component communication
-3. **Composable Integration**: Use existing composables for state management
-4. **Progressive Decomposition**: Extract components incrementally to maintain functionality
-
-### Implementation Strategy
-1. **Extract ProjectSwitcher**: Move project switching logic to dedicated component
-2. **Extract NotesNav**: Isolate navigation state and view selection logic
-3. **Extract FolderTree**: Separate folder display and selection logic
-4. **Extract NotesList**: Isolate note listing and card display logic  
-5. **Extract NoteDetail**: Separate note content display and editing
-6. **Update Notes.vue**: Become orchestration component managing component interactions
-
-### State Management Integration
- **useNotesNavigation**: Manages navigation state (All/Recent/Project)
- **useNotesFiltering**: Handles filtering logic based on navigation and folder selection
- **useNotesLayout**: Manages responsive layout and panel visibility
- **Component State**: Each component manages its own internal UI state
- **Shared State**: Project selection and note filtering coordinated through composables
-
-### Responsive Behavior
-
-Mobile:
- Hide sidebar. pop out panel when selected 
- show note list on small screens (existing behavior)
- when note list item is clicked, display note detail on full page. Cancel or go back to return to list
-
-Desktop: 
- Full three-column layout with all components visible
-
- **Transitions**: Smooth navigation between mobile panels
-
-## How to Evaluate
-
-### Success Criteria
- **Functional Parity**: All existing Notes page functionality preserved
- **Component Isolation**: Each component can be developed/tested independently  
- **Clear Responsibilities**: No overlapping concerns between components
- **State Clarity**: Clean data flow and state management patterns
- **Mobile Compatibility**: Responsive behavior maintains current UX
- **Performance**: No degradation in rendering or interaction performance
-
-### Testing Procedure
-1. **Functionality Validation**:
-   - Project switching works correctly
-   - All three navigation views (All/Recent/Project) function properly
-   - Folder selection affects note display appropriately
-   - Note selection and detail display works
-   - Mobile responsive behavior preserved
-
-2. **Component Isolation Testing**:
-   - Each component can be imported and used independently
-   - Component props and events are clearly defined
-   - No tight coupling between components
-
-3. **Integration Testing**:
-   - Components communicate correctly through props/events
-   - State management composables integrate properly
-   - User workflows function end-to-end
-
-4. **Performance Validation**:
-   - Page load time unchanged or improved
-   - Interaction responsiveness maintained
-   - Memory usage stable or improved
-
-### Implementation Validation
- **Code Review**: Clean component structure with single responsibilities
- **Type Safety**: Full TypeScript coverage with proper component prop types
- **Documentation**: Each component has clear interface documentation
- **Tests**: Unit tests for individual components and integration tests for workflows
-
-## Observations
-
- [problem] Monolithic Notes.vue component creates maintenance and testing challenges #component-architecture
- [solution] Component decomposition improves separation of concerns and testability #refactoring
- [pattern] Progressive extraction maintains functionality while improving structure #incremental-improvement
- [interaction] NotesNav and FolderTree have conditional interaction based on selected view #state-management
- [constraint] Mobile responsive behavior must be preserved during decomposition #responsive-design
- [scope] Current editing and frontmatter capabilities remain unchanged #scope-limitation
- [validation] Functional parity is critical success criteria for this refactoring #validation-strategy
- [implementation] Folder selection now properly integrates with directoryList API for accurate filtering #api-integration
- [fix] FolderTree selection functionality completed - works across all navigation views #feature-complete
- [ux-improvement] FolderTree selection automatically switches NotesNav to Project view for clear user feedback #user-experience
-
-## Relations
-
- depends_on [[SPEC-1: Specification-Driven Development Process]]
- implements [[Current Notes.vue functionality]]
- prepares_for [[Future rich editor spec]]
- prepares_for [[Future frontmatter editing spec]]
-## Implementation Progress
-
-### Components
-
-1. **ProjectSwitcher** (`~/components/notes/ProjectSwitcher.vue`)
-   - ✅ Top-left dropdown for project switching
-   - ✅ Integrates with Pinia project store
-   - ✅ Handles project switching with proper state reset
-   - ✅ Responsive collapsed/expanded states
-   - ✅ Expanded menu shows available projects and a Manage Projects option that navigates to the /settings/projects page
-   - ✅ Simplified component following SortingToggle pattern - clean Props/Emits interface, uses ProjectItem type directly 
-
-2. **NotesNav** (`~/components/notes/NotesNav.vue`)
-   - ✅ Three mutually exclusive views: All/Recent/Project
-   - ✅ Dynamic project title based on selected project
-   - ✅ Clean props down, events up pattern
-   - ✅ Responsive collapsed/expanded states with tooltips
-   - ✅ The label for the Project selection should be the folder name for the project, not the project name
-
-3. **FolderTree** (`~/components/notes/FolderTree.vue`)
-   - ✅ Nested folder tree view for filtering
-   - ✅ Uses `useFolderTree()` composable for data
-   - ✅ Emits `folder-selected` events properly
-   - ✅ Handles loading, error, and empty states
-   - ✅ Includes companion `FolderTreeNode.vue` component
-   - ✅ The current folder should be visibly selected in the tree  
-
-4. **NotesList** (`~/components/notes/NotesList.vue`)
-   - ✅ Vertically scrolling note summary cards
-   - ✅ Shows title, updated time (relative), and content preview
-   - ✅ Badge system for tags with variant logic
-   - ✅ v-model integration for selectedNote
-   - ✅ Smooth transitions and animations
-   - ✅ Contextual title: The current folder name should be displayed at the top of the Notes list, or "All Notes", or "Recent" if they are selected
-   - ✅ The title header should contain a toggle component to allow sorting with Lucide icon labels
-     - sorting options:
-       - name (asc/desc) - default 
-       - file updated time (asc/desc)
-     - If "Recent" notes nav option is selected the default order should be updated in descending order (recent first)
-
-5. **NoteDisplay** (`~/components/notes/NoteDisplay.vue` - equivalent to spec's NoteDetail)
-   - ✅ Full note content display
-   - ✅ Edit/view mode toggle
-   - ✅ Header with frontmatter information
-   - ✅ Markdown rendering capabilities
-   - ✅ Current textarea implementation preserved
-
-### Architecture Requirements
-
-1. **Component Isolation**: Each component can be developed/tested independently ✅
-2. **Single Responsibility**: Each component handles one primary concern ✅
-3. **Clear Data Flow**: Props down, events up pattern implemented ✅
-4. **Composable Integration**: Uses existing composables for state management ✅
-5. **Responsive Behavior**: Mobile/desktop layout preserved ✅
-
-### State Management Integration
-
- **useNotesNavigation**: Manages navigation state (All/Recent/Project) ✅
- **useNotesFiltering**: Handles filtering logic based on navigation and folder selection ✅
- **useNotesLayout**: Manages responsive layout and panel visibility ✅
- **Component State**: Each component manages its own internal UI state ✅
-
-### Interaction Logic
-
- Only one NotesNav view active at a time ✅
- All/Recent views ignore folder selection ✅ 
- Project view respects folder selection ✅
- Project switching resets to "All notes" view ✅
-
-### TypeScript Coverage
-
- All components have full TypeScript coverage ✅
- Component props and events properly typed ✅
- No TypeScript errors in codebase ✅
-
-### Success Criteria Validation
-
-1. **Functional Parity**: All existing Notes page functionality preserved ✅
-2. **Component Isolation**: Each component can be developed/tested independently ✅
-3. **Clear Responsibilities**: No overlapping concerns between components ✅
-4. **State Clarity**: Clean data flow and state management patterns ✅
-5. **Mobile Compatibility**: Responsive behavior maintains current UX ✅
-6. **Performance**: No degradation in rendering or interaction performance ✅
-
-## Implementation Decisions
-
-### Architectural Patterns
-
-1. **Composition API + `<script setup>`**: All components use modern Vue 3 syntax
-2. **Pinia Store Integration**: Project switching handled through reactive store
-3. **Composable Pattern**: State management distributed across focused composables
-4. **Event-Driven Communication**: Clean parent-child communication via events
-5. **Responsive-First Design**: Mobile/desktop layouts handled natively
-
-### Key Technical Choices
-
-1. **Progressive Enhancement**: Mobile-first responsive design with desktop enhancements
-2. **State Reset Logic**: Project switching properly resets navigation, search, and selection state
-3. **Performance Optimizations**: Efficient re-rendering with proper key usage and transitions
-4. **Accessibility**: Screen reader support, tooltips, keyboard navigation
-5. **Type Safety**: Full TypeScript coverage with proper component prop definitions
-
-### Quality Metrics
-
- **Code Maintainability**: High - each component is focused and independently testable
- **Performance**: Excellent - no performance degradation from decomposition  
- **User Experience**: Preserved - all existing functionality and responsive behavior maintained
- **Developer Experience**: Improved - cleaner component structure for future development
@@ -32,13 +32,13 @@ Related Github issue: https://github.com/basicmachines-co/basic-memory-cloud/iss

 ## Status

-**Current Status**: **ALL PHASES COMPLETE** ✅ **PRODUCTION DEPLOYED**
-**Target**: Fix Claude iOS session ID consistency issues ✅ **ACHIEVED**
-**Draft PR**: https://github.com/basicmachines-co/basic-memory/pull/298 ✅ **MERGED & DEPLOYED**
+**Current Status**: **Phase 1 Implementation Complete** ✅
+**Target**: Fix Claude iOS session ID consistency issues
+**Draft PR**: https://github.com/basicmachines-co/basic-memory/pull/298

-### 🎉 **COMPLETE SUCCESS - PRODUCTION READY**
+### 🎉 **MAJOR MILESTONE ACHIEVED**

-**ALL PHASES OF SPEC-6 IMPLEMENTATION COMPLETE!** The stateless architecture has been successfully implemented across both Basic Memory core and Basic Memory Cloud, representing a **fundamental architectural improvement** that completely solves the Claude iOS compatibility issue while providing superior scalability and reliability.
+The complete stateless architecture has been successfully implemented for Basic Memory's MCP server! This represents a **fundamental architectural improvement** that solves the Claude iOS compatibility issue while making the entire system more robust and predictable.

 #### Implementation Summary:
 - **16 files modified** with 582 additions and 550 deletions
@@ -49,12 +49,10 @@ Related Github issue: https://github.com/basicmachines-co/basic-memory-cloud/iss

 ### Progress Summary

-✅ **Complete Stateless Architecture Implementation (All 17 tools)** - **PRODUCTION DEPLOYED**
- Stateless `get_active_project()` function implemented and deployed ✅
- All session state dependencies removed across entire MCP server ✅
- All MCP tools require explicit `project` parameter as first argument ✅
- **Cloud Service**: Redis removed, stateless HTTP enabled ✅
- **Production Validation**: Comprehensive testing completed with 100% success ✅
+✅ **Complete Stateless Architecture Implementation (All 17 tools)**
+- Stateless `get_active_project()` function implemented and deployed
+- All session state dependencies removed across entire MCP server
+- All MCP tools require explicit `project` parameter as first argument

 ✅ **Content Management Tools Complete (6/6 tools)**
 - `write_note`, `read_note`, `delete_note`, `edit_note` ✅
@@ -308,12 +306,12 @@ File: experiments/Neural Network Results.md
 Permalink: research-project/neural-network-results
 ```

-### Phase 2: Cloud Service Simplification (basic-memory-cloud repository) ✅ **COMPLETE**
+### Phase 2: Cloud Service Simplification (basic-memory-cloud repository)

-#### ✅ Remove Session Infrastructure **COMPLETE**
-1. ✅ Delete `apps/mcp/src/basic_memory_cloud_mcp/middleware/session_state.py`
-2. ✅ Delete `apps/mcp/src/basic_memory_cloud_mcp/middleware/session_logging.py`
-3. ✅ Update `apps/mcp/src/basic_memory_cloud_mcp/main.py`:
+#### Remove Session Infrastructure
+1. Delete `apps/mcp/src/basic_memory_cloud_mcp/middleware/session_state.py`
+2. Delete `apps/mcp/src/basic_memory_cloud_mcp/middleware/session_logging.py`
+3. Update `apps/mcp/src/basic_memory_cloud_mcp/main.py`:
   ```python
   # Remove session middleware
   # server.add_middleware(SessionStateMiddleware)
@@ -322,16 +320,15 @@ Permalink: research-project/neural-network-results
   mcp = FastMCP(name="basic-memory-mcp", stateless_http=True)
   ```

-#### ✅ Deployment Simplification **COMPLETE**
-1. ✅ Remove Redis from `fly.toml`
-2. ✅ Remove Redis environment variables
-3. ✅ Update health checks to not depend on Redis
-4. ✅ Production deployment verified working with stateless architecture
+#### Deployment Simplification
+1. Remove Redis from `fly.toml`
+2. Remove Redis environment variables
+3. Update health checks to not depend on Redis

-### Phase 3: Conversational Project Management ✅ **COMPLETE**
+### Phase 3: Conversational Project Management

-#### ✅ Claude Behavior Pattern **VERIFIED WORKING**
-1. ✅ **Project Discovery**:
+#### Claude Behavior Pattern
+1. **Project Discovery**:
   ```
   Claude: Let me check your recent activity...
   [calls recent_activity() - no project needed for discovery]
@@ -343,22 +340,20 @@ Permalink: research-project/neural-network-results
   Which project should I use for this operation?
   ```

-2. ✅ **Context Maintenance**:
+2. **Context Maintenance**:
   ```
   User: Use research-project
   Claude: Working in research-project.
   [All subsequent operations use project="research-project"]
   ```

-3. ✅ **Explicit Project Switching**:
+3. **Explicit Project Switching**:
   ```
   User: Check work-notes for that meeting summary
   Claude: Let me search work-notes for the meeting summary.
   [Uses project="work-notes" for specific operation]
   ```

-**Validation**: Comprehensive testing confirmed all conversational patterns work naturally with the stateless architecture.
-
 ## How to Evaluate

 ### Success Criteria
@@ -368,32 +363,28 @@ Permalink: research-project/neural-network-results
 - [x] All MCP tools validate project exists before execution
 - [x] `switch_project` and `get_current_project` tools removed
 - [x] All responses display target project clearly
- [x] No Redis dependencies in deployment (Phase 2: Cloud Service) ✅ **COMPLETE**
+- [ ] No Redis dependencies in deployment (Phase 2: Cloud Service)
 - [x] `recent_activity` shows project distribution with ProjectActivitySummary

-#### 2. Cross-Client Compatibility Testing ✅ **COMPLETE**
+#### 2. Cross-Client Compatibility Testing
 Test identical operations across all clients:
- [x] **Claude Desktop**: All operations work with explicit projects ✅
- [x] **Claude Code**: All operations work with explicit projects ✅
- [x] **Claude Mobile iOS**: All operations work with explicit projects ✅ **CRITICAL SUCCESS**
- [x] **API clients**: All operations work with explicit projects ✅
- [x] **CLI tools**: All operations work with explicit projects ✅
+- [ ] **Claude Desktop**: All operations work with explicit projects
+- [ ] **Claude Code**: All operations work with explicit projects
+- [ ] **Claude Mobile iOS**: All operations work with explicit projects
+- [ ] **API clients**: All operations work with explicit projects
+- [ ] **CLI tools**: All operations work with explicit projects

-**Critical Achievement**: Claude iOS mobile client session tracking issues completely eliminated through stateless architecture.
+#### 3. Session Independence Verification
+- [ ] Operations work identically with/without session tracking
+- [ ] No behavioral differences between clients
+- [ ] Mobile client session ID changes do not affect operations
+- [ ] Redis can be completely removed without functional impact

-#### 3. Session Independence Verification ✅ **COMPLETE**
- [x] Operations work identically with/without session tracking ✅
- [x] No behavioral differences between clients ✅
- [x] Mobile client session ID changes do not affect operations ✅
- [x] Redis can be completely removed without functional impact ✅
-
-**Production Validation**: Redis removed from production deployment with zero functional impact.
-
-#### 4. Performance & Scaling ✅ **COMPLETE**
- [x] `stateless_http=True` enabled successfully ✅
- [x] No Redis memory usage ✅
- [x] Horizontal scaling possible (multiple MCP instances) ✅
- [x] Response times unchanged or improved ✅
+#### 4. Performance & Scaling
+- [ ] `stateless_http=True` enabled successfully
+- [ ] No Redis memory usage
+- [ ] Horizontal scaling possible (multiple MCP instances)
+- [ ] Response times unchanged or improved

 #### 5. User Experience Testing
 **Project Discovery Flow**:
@@ -411,13 +402,11 @@ Test identical operations across all clients:
 - [x] Users always know which project is being operated on
 - [x] No confusion about "current project" state

-#### 6. Migration Safety ✅ **COMPLETE**
- [x] Backward compatibility period with optional project parameter ✅
- [x] Clear migration documentation for existing users ✅
- [x] Data integrity maintained during transition ✅
- [x] No data loss during migration ✅
-
-**Production Migration**: Successfully deployed to production with zero data loss and maintained system integrity.
+#### 6. Migration Safety
+- [ ] Backward compatibility period with optional project parameter
+- [ ] Clear migration documentation for existing users
+- [ ] Data integrity maintained during transition
+- [ ] No data loss during migration

 ### Test Scenarios

@@ -13,26 +13,21 @@ tags:

 # SPEC-7: POC to spike Tigris/Turso for local access to cloud data

-> **Status Update**: ✅ **Phase 1 COMPLETE** (September 20, 2025)
-> TigrisFS mounting validated successfully in containerized environments. Container startup, filesystem mounting, and Fly.io integration all working correctly. Ready for Phase 2 (Turso database integration).
-> See: [`SPEC-7-PHASE-1-RESULTS.md`](./SPEC-7-PHASE-1-RESULTS.md)
-
 ## Why

 Current basic-memory-cloud architecture uses Fly volumes for tenant file storage, which creates several limitations:

-We could enable a revolutionary user experience: **local editing (or at least view access) of cloud-stored files** while maintaining Basic Memory's existing filesystem assumptions.
-
 1. **Storage Scalability**: Fly volumes require pre-provisioning and don't auto-scale with usage
-2. **Single Instance**: Volumes can only be mounted to one fly machine instance
-3. **Cost Model**: Volume pricing vs object storage pricing may be less favorable at scale
-4. **Local Development**: No way for users to mount their cloud tenant files locally for real-time editing
-5. **Multi-Region**: Volumes are region-locked, limiting global deployment flexibility
-6. **Backup/Disaster Recovery**: Object storage provides better durability and replication options
+2. **Cost Model**: Volume pricing vs object storage pricing may be less favorable at scale
+3. **Local Development**: No way for users to mount their cloud tenant files locally for real-time editing
+4. **Multi-Region**: Volumes are region-locked, limiting global deployment flexibility
+5. **Backup/Disaster Recovery**: Object storage provides better durability and replication options

-Basic Memory requires POSIX filesystem semantics but could benefit from object storage durability and accessibility. By combining:
- **Tigris object storage and TigrisFS** for file persistence in bucket stoage via a POSIX filesystem on the tenant instance
- **Turso/libSQL** for SQLite indexing (replacing local .db files). Sqlite on NFS volumes is disouraged. 
+The core insight is that Basic Memory requires POSIX filesystem semantics but could benefit from object storage durability and accessibility. By combining:
+- **Tigris object storage** for file persistence (via rclone mount)
+- **Turso/libSQL** for SQLite indexing (replacing local .db files)
+
+We could enable a revolutionary user experience: **local editing of cloud-stored files** while maintaining Basic Memory's existing filesystem assumptions.

 ## What

@@ -41,126 +36,55 @@ This specification defines a proof-of-concept to validate the technical feasibil
 **Affected Areas:**
 - **Storage Architecture**: Replace Fly volumes with Tigris object storage
 - **Database Architecture**: Replace local SQLite with Turso remote database
- **Container Setup**: Add TigrisFS mounting in tenant containers
+- **Container Setup**: Add rclone mounting in tenant containers
 - **Local Development**: Enable local mounting of cloud tenant data
 - **Basic Memory Core**: Validate unchanged operation over mounted filesystems

 **Key Components:**
- **Tigris Storage**: Globally caching S3-compatible object storage via Fly.io integration
- **TigrisFS**: Purpose-built FUSE filesystem with intelligent caching
+- **Tigris Storage**: S3-compatible object storage via Fly.io integration
+- **rclone NFS Mount**: Native NFS mounting without FUSE dependencies
 - **Turso Database**: Hosted libSQL for SQLite replacement
 - **Single-Tenant Model**: One bucket + one database per tenant (simplified isolation)

-## Architectural Overview & Key Insights
-
-### TigrisFS
-
-Unlike standard S3 mounting approaches, **TigrisFS is a purpose-built FUSE filesystem** optimized for object storage with several critical advantages:
-
-1. **Eliminates Fly Volume Limitations**
-   - No single-machine attachment constraints
-   - No pre-provisioning of storage capacity
-   - Enables horizontal scaling and zero-downtime deployments
-   - Automatic global CDN caching at Fly.io edge locations
-
-2. **Intelligent Caching Architecture**
-   - 1-4GB+ configurable memory cache for read/write operations
-   - Write-back caching for improved performance
-   - Metadata cache to reduce API calls
-   - "Close to Redis speed" for small object retrieval
-
-3. **Cost-Effective Model**
-   - Pay only for storage used and transferred
-   - No wasted capacity from over-provisioning
-   - Automatic global replication included
-   - S3 durability with CDN performance
-
-### API-Driven Architecture Eliminates File Watching Concerns
-
-**Critical Insight**: All file access (reads/writes) in basic-memory-cloud go through the API layer:
- **MCP Tools → API**: All Basic Memory operations use FastAPI endpoints
- **Web App → API**: Frontend uses API for all data modifications
- **File watching is NOT required** for cloud operations, unlike local BM which uses the WatchService to monitor file changes.
-
-This means:
- **Cloud Operations**: Manual sync after API writes is sufficient
- **Local Development**: File watching only matters for local editing experience
- **Performance Risk**: Dramatically reduced since we're not dependent on inotify over network filesystems
-
-### Realistic Local Access Expectations
-
-**Baseline Functionality (Guaranteed):**
- Read-only mounting for browsing cloud files
- Easy download/upload of entire projects
- File copying via standard filesystem operations
-
-**Stretch Goal (Test in POC):**
- Live editing with eventual consistency (1-5 second delays acceptable)
- Automatic sync for local changes
- Not required for core functionality - pure upside if it works
-
-### Production Deployment Advantages
-
-1. **Multi-Region Deployment**: Tigris handles global replication automatically
-2. **Zero-Downtime Updates**: No volume detach/attach during deployments
-3. **Tenant Migrations**: Simply update credentials, no data movement
-4. **Disaster Recovery**: Built into S3 durability model (99.999999999% durability)
-5. **Auto-Scaling**: Storage scales with usage, no capacity planning needed
-
-
 ## How (High Level)

-### POC Approach: Server-First Validation
+### Phase 1: Local POC Validation
+- [ ] Set up Tigris bucket with test data
+- [ ] Configure rclone NFS mount locally
+- [ ] Test Basic Memory operations over mounted filesystem
+- [ ] Measure performance characteristics and identify issues
+- [ ] Validate file watching, sync operations, and concurrent access patterns

-**Rationale**: Start with server-side TigrisFS mounting because:
- Local access is meaningless if cloud containers can't mount TigrisFS reliably
- Container startup and API performance are critical path blockers
- TigrisFS compatibility with Basic Memory operations must be proven first
- Each phase gates the next - no point testing local access if server-side fails
-
-### Phase 1: Server-Side TigrisFS Validation (Critical Foundation) ✅ COMPLETE
- [x] Set up Tigris bucket with test data via Fly.io integration
- [x] Create container image with TigrisFS support and dependencies
- [x] Test TigrisFS mounting in containerized environment
- [x] Run Basic Memory API operations over mounted TigrisFS
- [x] Validate all filesystem operations work correctly
- [x] Measure container startup time and resource usage
-
-**Production Validation Results**: Container successfully deployed and operated for 42+ minutes serving real MCP requests with repository queries, knowledge graph navigation, and full Basic Memory API functionality over TigrisFS-mounted storage.
-
-### Phase 2: Database Migration to Turso
+### Phase 2: Database Migration
 - [ ] Set up Turso account and test database
 - [ ] Modify Basic Memory to accept external DATABASE_URL
- [ ] Test all MCP tools with remote SQLite via Turso
+- [ ] Test all operations with remote SQLite via Turso
 - [ ] Validate performance and functionality parity
- [ ] Test API write → manual sync workflow in container

-### Phase 3: Production Container Integration
- [ ] Implement tenant-specific credential management for buckets
- [x] Test container startup with automatic TigrisFS mounting
+### Phase 3: Container Integration
+- [ ] Create container image with rclone + NFS support
+- [ ] Implement tenant-specific credential management
+- [ ] Test container startup with automatic mounting
 - [ ] Validate isolation between tenant containers
- [ ] Test API operations under realistic load
- [ ] Measure performance vs current Fly volume setup

-### Phase 4: Local Access Validation (Bonus Feature)
- [ ] Test local TigrisFS mounting of tenant data
- [ ] Validate read-only access for browsing/downloading
- [ ] Test file copying and upload workflows
+### Phase 4: Local Access Validation
+- [ ] Test local rclone mounting of tenant data
+- [ ] Validate real-time file editing experience
+- [ ] Test conflict resolution and sync behavior
 - [ ] Measure latency impact on user experience
- [ ] Test live editing if file watching works (stretch goal)

 ### Architecture Overview
 ```
 Local Development:
 ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│ Local TigrisFS  │───▶│ Tigris Bucket   │◀───│ Tenant Container│
-│ Mount           │    │ (Global CDN)    │    │ TigrisFS mount  │
+│ Local rclone    │───▶│ Tigris Bucket   │◀───│ Tenant Container│
+│ NFS Mount       │    │ (S3 storage)    │    │ rclone mount    │
 └─────────────────┘    └─────────────────┘    └─────────────────┘
         │                                              │
         ▼                                              ▼
 ┌─────────────────┐                            ┌─────────────────┐
 │ Basic Memory    │                            │ Basic Memory    │
-│ (local files)   │                            │ API + mounted   │
+│ (local files)   │                            │ (mounted files) │
 └─────────────────┘                            └─────────────────┘
         │                                              │
         ▼                                              ▼
@@ -168,157 +92,102 @@ Local Development:
 │ Turso Database  │◀───────────────────────────│ Turso Database  │
 │ (shared index)  │                            │ (shared index)  │
 └─────────────────┘                            └─────────────────┘
-
-Flow: API writes → Manual sync → Index update
-Local: File watching (if available) → Auto sync
 ```

 ## How to Evaluate

 ### Success Criteria
- [x] **Filesystem Compatibility**: Basic Memory operates without modification over TigrisFS-mounted storage
- [x] **Performance Acceptable**: API-driven operations perform within acceptable latency (target: <500ms for typical operations)
+- [ ] **Filesystem Compatibility**: Basic Memory operates without modification over rclone-mounted Tigris storage
+- [ ] **Performance Acceptable**: File operations complete within 2x local filesystem latency
 - [ ] **Database Functionality**: All Basic Memory features work with Turso remote SQLite
- [x] **Container Reliability**: Tenant containers start successfully with automatic TigrisFS mounting
- [ ] **Local Access Baseline**: Users can mount cloud files locally for read-only browsing and file copying
- [x] **Data Isolation**: Tenant data remains properly isolated using bucket/database separation
- [ ] **Local Access Stretch**: Live editing with eventual sync (1-5 second delays acceptable)
+- [ ] **Container Reliability**: Tenant containers start successfully with automatic mounting
+- [ ] **Local Access**: Users can mount and edit cloud files locally with real-time sync
+- [ ] **Data Isolation**: Tenant data remains properly isolated using bucket/database separation

 ### Testing Procedure
+1. **Local Filesystem Test**:
+   ```bash
+   # Mount Tigris bucket locally
+   rclone nfsmount tigris:test-bucket ~/tigris-test --vfs-cache-mode writes

-#### Phase 1: Server-Side Foundation Testing
-1. **Container TigrisFS Test**:
-   ```dockerfile
-   # Test container with TigrisFS mounting
-   FROM python:3.12
-   RUN apt-get update && apt-get install -y tigrisfs
-
-   # Test startup script
-   #!/bin/bash
-   tigrisfs --memory-limit 2048 $TIGRIS_BUCKET /app/data --daemon
-   cd /app/data && basic-memory sync
-   basic-memory-api --data-dir /app/data
+   # Run Basic Memory operations
+   cd ~/tigris-test && basic-memory sync --watch
+   # Test: create notes, search, file watching, bulk operations
   ```

-2. **API Operations Validation**:
+2. **Database Migration Test**:
   ```bash
-   # Test all MCP operations over TigrisFS
-   curl -X POST /api/write_note -d '{"title":"test","content":"content"}'
-   curl -X GET /api/read_note/test
-   curl -X GET /api/search_notes?q=content
-   # Measure: response times, error rates, data consistency
-   ```
-
-#### Phase 2: Database Integration Testing
-3. **Turso Integration Test**:
-   ```bash
-   # Configure Turso connection in container
+   # Configure Turso connection
   export DATABASE_URL="libsql://test-db.turso.io?authToken=..."

   # Test all MCP tools with remote database
   basic-memory tools # Test each tool functionality
-   # Test API write → manual sync workflow
   ```

-#### Phase 3: Production Readiness Testing
+3. **Container Integration Test**:
+   ```dockerfile
+   # Test container with rclone mounting
+   FROM python:3.12
+   RUN apt-get update && apt-get install -y rclone nfs-common
+   # ... test startup and mounting process
+   ```
+
 4. **Performance Benchmarking**:
-   - Container startup time with TigrisFS mounting
-   - API operation response times (target: <500ms for typical operations)
-   - Search query performance with Turso (target: comparable to local SQLite)
-   - TigrisFS cache hit rates and memory usage
-   - Concurrent tenant isolation
-
-#### Phase 4: Local Access Testing (If Phase 1-3 Succeed)
-5. **Local Access Validation**:
-   ```bash
-   # Test read-only access
-   tigrisfs tenant-bucket ~/local-tenant
-   ls -la ~/local-tenant  # Browse files
-   cp ~/local-tenant/notes/* ~/backup/  # Copy files
-
-   # Test file watching (stretch goal)
-   echo "test" > ~/local-tenant/test.md
-   # Check if changes sync to cloud
-   ```
-
-### Go/No-Go Criteria by Phase
- **Phase 1**: Container must start successfully and serve API requests over TigrisFS
- **Phase 2**: All MCP tools must work with Turso with <2x latency increase
- **Phase 3**: Performance must be within 50% of current Fly volume setup
- **Phase 4**: Local mounting must work reliably for read-only access
+   - File creation/read/write operations (target: <2x local latency)
+   - Search query performance (target: comparable to local SQLite)
+   - File watching responsiveness (target: events within 1-2 seconds)
+   - Concurrent operation handling

 ### Risk Assessment
-**Moderate Risk Items (Mitigated by API-First Architecture)**:
- [ ] TigrisFS performance for local access may have higher latency than local filesystem
- [ ] File watching (`inotify`) over FUSE may be unreliable for local development
- [ ] Network interruptions could cause filesystem errors during local editing
- [ ] Write-back caching could cause data loss if container crashes during flush
-
-**Low Risk Items (API-First Eliminates)**:
- [ ] ~~Real-time file watching~~ - Not required for cloud operations
- [ ] ~~Concurrent write consistency~~ - Single-tenant model with API coordination
- [ ] ~~S3 rate limits~~ - TigrisFS intelligent caching handles this
+**High Risk Items**:
+- [ ] NFS-over-S3 performance may be insufficient for real-time operations
+- [ ] File watching (`inotify`) over NFS may be unreliable
+- [ ] Network interruptions could cause filesystem errors
+- [ ] Concurrent access patterns might hit S3 rate limits

 **Mitigation Strategies**:
- **Performance**: Comprehensive benchmarking with realistic workloads
- **Reliability**: Graceful degradation to read-only local access if live editing fails
- **Data Safety**: Regular sync intervals and write-through mode for critical operations
- **Fallback**: Keep Fly volumes as backup deployment option
+- Comprehensive performance testing before committing to architecture
+- Fallback plan to S3-native storage backend if filesystem approach fails
+- Extensive error handling and retry logic for network issues

 ### Metrics to Track
- **API Latency**: Response times for MCP tools and web operations
- **Cache Effectiveness**: TigrisFS cache hit rates and memory usage
- **Local Access Performance**: File browsing and copying speeds
- **Reliability**: Success rate of mount operations and data consistency
- **Cost**: Storage usage, API calls, and network transfer costs vs current volumes
+- **Latency**: File operation response times (read/write/watch)
+- **Reliability**: Success rate of file operations over time
+- **Throughput**: Concurrent file operations and search queries
+- **User Experience**: Perceived performance for local mounting use case

 ## Notes

 ### Key Architectural Decisions
 - **Single tenant per bucket/database**: Simplifies isolation and credential management
 - **Maintain POSIX compatibility**: Preserve Basic Memory's existing filesystem assumptions
- **TigrisFS over rclone**: Purpose-built for object storage with intelligent caching
+- **NFS over FUSE**: Better compatibility and performance characteristics
 - **Turso for SQLite**: Leverages specialized remote SQLite expertise
- **API-first approach**: Eliminates file watching dependency for cloud operations

 ### Alternative Approaches Considered
 - **S3-native storage backend**: Would require Basic Memory architecture changes
 - **Hybrid approach**: Local files + cloud sync (adds complexity)
- **Standard rclone mounting**: Less optimized than TigrisFS for object storage workloads
- **Keep Fly volumes**: Maintains current limitations but proven reliability
+- **FUSE mounting**: More platform dependencies and kernel requirements

 ### Integration Points
 - [ ] Fly.io Tigris integration for bucket provisioning
 - [ ] Turso account setup and database provisioning
- [ ] Container image modifications for TigrisFS support
+- [ ] Container image modifications for rclone support
 - [ ] Credential management for tenant isolation
- [ ] API modification for manual sync triggers
- [ ] Local client setup documentation for TigrisFS mounting

 ## Observations

 - [architecture] Tigris/Turso split cleanly separates file storage from indexing concerns #storage-separation
- [breakthrough] API-first architecture eliminates file watching dependency for cloud operations #api-first-advantage
 - [user-experience] Local mounting of cloud files could be revolutionary for knowledge management #local-cloud-hybrid
 - [compatibility] Maintaining POSIX filesystem assumptions preserves Basic Memory's local/cloud compatibility #architecture-preservation
 - [simplification] Single tenant per bucket eliminates complex multi-tenancy in storage layer #tenant-isolation
- [performance] TigrisFS intelligent caching could provide near-local performance for common operations #tigrisfs-advantage
- [deployment] Zero-downtime updates become trivial without volume constraints #deployment-simplification
+- [risk] NFS-over-S3 performance characteristics are unproven for real-time operations #performance-risk
 - [benefit] Object storage pricing model could be more favorable than volume pricing #cost-optimization
- [innovation] Read-only local access alone would address major SaaS limitation #competitive-advantage
- [risk-mitigation] API-driven sync reduces performance requirements vs real-time file watching #risk-reduction
+- [innovation] Real-time local editing of cloud-stored files addresses major SaaS limitation #competitive-advantage

 ## Relations

 - implements [[SPEC-6 Explicit Project Parameter Architecture]]
 - requires [[Fly.io Tigris Integration]]
 - enables [[Local Cloud File Access]]
- alternative_to [[Fly Volume Storage]]
-
-## Links
- https://fly.io/hello/tigris
- https://fly.io/docs/tigris/
- https://www.tigrisdata.com/docs/sdks/fly/data-migration-with-flyctl/
- https://www.tigrisdata.com/docs/training/tigrisfs/
- https://www.tigrisdata.com/blog/tigris-filesystem/
- https://www.tigrisdata.com/docs/quickstarts/rclone/
+- alternative_to [[Fly Volume Storage]]
@@ -1,886 +0,0 @@
---
-title: 'SPEC-8: TigrisFS Integration for Tenant API'
-Date: September 22, 2025
-Status: Phase 3.6 Complete - Tenant Mount API Endpoints Ready for CLI Implementation
-Priority: High
-Goal: Replace Fly volumes with Tigris bucket provisioning in production tenant API
-permalink: spec-8-tigris-fs-integration
---
-
-## Executive Summary
-
-Based on SPEC-7 Phase 4 POC testing, this spec outlines productizing the TigrisFS/rclone implementation in the Basic Memory Cloud tenant API. 
-We're moving from proof-of-concept to production integration, replacing Fly volume storage with Tigris bucket-per-tenant architecture.
-
-## Current Architecture (Fly Volumes)
-
-### Tenant Provisioning Flow
-```python
-# apps/cloud/src/basic_memory_cloud/workflows/tenant_provisioning.py
-async def provision_tenant_infrastructure(tenant_id: str):
-    # 1. Create Fly app
-    # 2. Create Fly volume  ← REPLACE THIS
-    # 3. Deploy API container with volume mount
-    # 4. Configure health checks
-```
-
-### Storage Implementation
- Each tenant gets dedicated Fly volume (1GB-10GB)
- Volume mounted at `/app/data` in API container
- Local filesystem storage with Basic Memory indexing
- No global caching or edge distribution
-
-## Proposed Architecture (Tigris Buckets)
-
-### New Tenant Provisioning Flow
-```python
-async def provision_tenant_infrastructure(tenant_id: str):
-    # 1. Create Fly app
-    # 2. Create Tigris bucket with admin credentials  ← NEW
-    # 3. Store bucket name in tenant record  ← NEW
-    # 4. Deploy API container with TigrisFS mount using admin credentials
-    # 5. Configure health checks
-```
-
-### Storage Implementation
- Each tenant gets dedicated Tigris bucket
- TigrisFS mounts bucket at `/app/data` in API container
- Global edge caching and distribution
- Configurable cache TTL for sync performance
-
-## Implementation Plan
-
-### Phase 1: Bucket Provisioning Service
-
-**✅ IMPLEMENTED: StorageClient with Admin Credentials**
-```python
-# apps/cloud/src/basic_memory_cloud/clients/storage_client.py
-class StorageClient:
-    async def create_tenant_bucket(self, tenant_id: UUID) -> TigrisBucketCredentials
-    async def delete_tenant_bucket(self, tenant_id: UUID, bucket_name: str) -> bool
-    async def list_buckets(self) -> list[TigrisBucketResponse]
-    async def test_tenant_credentials(self, credentials: TigrisBucketCredentials) -> bool
-```
-
-**Simplified Architecture Using Admin Credentials:**
- Single admin access key with full Tigris permissions (configured in console)
- No tenant-specific IAM user creation needed
- Bucket-per-tenant isolation for logical separation
- Admin credentials shared across all tenant operations
-
-**Integrate with Provisioning workflow:**
-```python
-# Update tenant_provisioning.py
-async def provision_tenant_infrastructure(tenant_id: str):
-    storage_client = StorageClient(settings.aws_access_key_id, settings.aws_secret_access_key)
-    bucket_creds = await storage_client.create_tenant_bucket(tenant_id)
-    await store_bucket_name(tenant_id, bucket_creds.bucket_name)
-    await deploy_api_with_tigris(tenant_id, bucket_creds)
-```
-
-### Phase 2: Simplified Bucket Management
-
-**✅ SIMPLIFIED: Admin Credentials + Bucket Names Only**
-
-Since we use admin credentials for all operations, we only need to track bucket names per tenant:
-
-1. **Primary Storage (Fly Secrets)**
-   ```bash
-   flyctl secrets set -a basic-memory-{tenant_id} \
-     AWS_ACCESS_KEY_ID="{admin_access_key}" \
-     AWS_SECRET_ACCESS_KEY="{admin_secret_key}" \
-     AWS_ENDPOINT_URL_S3="https://fly.storage.tigris.dev" \
-     AWS_REGION="auto" \
-     BUCKET_NAME="basic-memory-{tenant_id}"
-   ```
-
-2. **Database Storage (Bucket Name Only)**
-   ```python
-   # apps/cloud/src/basic_memory_cloud/models/tenant.py
-   class Tenant(BaseModel):
-       # ... existing fields
-       tigris_bucket_name: Optional[str] = None  # Just store bucket name
-       tigris_region: str = "auto"
-       created_at: datetime
-   ```
-
-**Benefits of Simplified Approach:**
- No credential encryption/decryption needed
- Admin credentials managed centrally in environment
- Only bucket names stored in database (not sensitive)
- Simplified backup/restore scenarios
- Reduced security attack surface
-
-### Phase 3: API Container Updates
-
-**Update API container configuration:**
-```dockerfile
-# apps/api/Dockerfile
-# Add TigrisFS installation
-RUN curl -L https://github.com/tigrisdata/tigrisfs/releases/latest/download/tigrisfs-linux-amd64 \
-    -o /usr/local/bin/tigrisfs && chmod +x /usr/local/bin/tigrisfs
-```
-
-**Startup script integration:**
-```bash
-# apps/api/tigrisfs-startup.sh (already exists)
-# Mount TigrisFS → Start Basic Memory API
-exec python -m basic_memory_cloud_api.main
-```
-
-**Fly.toml environment (optimized for < 5s startup):**
-```toml
-# apps/api/fly.tigris-production.toml
-[env]
-  TIGRISFS_MEMORY_LIMIT = '1024'     # Reduced for faster init
-  TIGRISFS_MAX_FLUSHERS = '16'       # Fewer threads for faster startup
-  TIGRISFS_STAT_CACHE_TTL = '30s'    # Balance sync speed vs startup
-  TIGRISFS_LAZY_INIT = 'true'        # Enable lazy loading
-  BASIC_MEMORY_HOME = '/app/data'
-
-# Suspend optimization for wake-on-network
-[machine]
-  auto_stop_machines = "suspend"     # Faster than full stop
-  auto_start_machines = true
-  min_machines_running = 0
-```
-
-### Phase 4: Local Access Features
-
-**CLI automation for local mounting:**
-```python
-# New CLI command: basic-memory cloud mount
-async def setup_local_mount(tenant_id: str):
-    # 1. Fetch bucket credentials from cloud API
-    # 2. Configure rclone with scoped IAM policy
-    # 3. Mount via rclone nfsmount (macOS) or FUSE (Linux)
-    # 4. Start Basic Memory sync watcher
-```
-
-**Local mount configuration:**
-```bash
-# rclone config for tenant
-rclone mount basic-memory-{tenant_id}: ~/basic-memory-{tenant_id} \
-  --nfs-mount \
-  --vfs-cache-mode writes \
-  --cache-dir ~/.cache/rclone/basic-memory-{tenant_id}
-```
-
-### Phase 5: TigrisFS Cache Sync Solutions
-
-**Problem**: When files are uploaded via CLI/bisync, the tenant API container doesn't see them immediately due to TigrisFS cache (30s TTL) and lack of inotify events on mounted filesystems.
-
-**Multi-Layer Solution:**
-
-**Layer 1: API Sync Endpoint** (Immediate)
-```python
-# POST /sync - Force TigrisFS cache refresh
-# Callable by CLI after uploads
-subprocess.run(["sync", "fsync /app/data"], check=True)
-```
-
-**Layer 2: Tigris Webhook Integration** (Real-time)
-https://www.tigrisdata.com/docs/buckets/object-notifications/#webhook
-```python
-# Webhook endpoint for bucket changes
-@app.post("/webhooks/tigris/{tenant_id}")
-async def handle_bucket_notification(tenant_id: str, event: TigrisEvent):
-    if event.eventName in ["OBJECT_CREATED_PUT", "OBJECT_DELETED"]:
-        await notify_container_sync(tenant_id, event.object.key)
-```
-
-**Layer 3: CLI Sync Notification** (User-triggered)
-```bash
-# CLI calls container sync endpoint after successful bisync
-basic-memory cloud bisync  # Automatically notifies container
-curl -X POST https://basic-memory-{tenant-id}.fly.dev/sync
-```
-
-**Layer 4: Periodic Sync Fallback** (Safety net)
-```python
-# Background task: fsync /app/data every 30s as fallback
-# Ensures eventual consistency even if other layers fail
-```
-
-**Implementation Priority:**
-1. Layer 1 (API endpoint) - Quick testing capability
-2. Layer 3 (CLI integration) - Improved UX
-3. Layer 4 (Periodic fallback) - Safety net
-4. Layer 2 (Webhooks) - Production real-time sync
-
-
-## Performance Targets
-
-### Sync Latency
- **Target**: < 5 seconds local→cloud→container
- **Configuration**: `TIGRISFS_STAT_CACHE_TTL = '5s'`
- **Monitoring**: Track sync metrics in production
-
-### Container Startup
- **Target**: < 5 seconds including TigrisFS mount
- **Fast retry**: 0.5s intervals for mount verification
- **Fallback**: Container fails fast if mount fails
-
-### Memory Usage
- **TigrisFS cache**: 2GB memory limit per container
- **Concurrent uploads**: 32 flushers max
- **VM sizing**: shared-cpu-2x (2048mb) minimum
-
-## Security Considerations
-
-### Bucket Isolation
- Each tenant has dedicated bucket
- IAM policies prevent cross-tenant access
- No shared bucket with subdirectories
-
-### Credential Security
- Fly secrets for runtime access
- Encrypted database backup for disaster recovery
- Credential rotation capability
-
-### Data Residency
- Tigris global edge caching
- SOC2 Type II compliance
- Encryption at rest and in transit
-
-## Operational Benefits
-
-### Scalability
- Horizontal scaling with stateless API containers
- Global edge distribution
- Better resource utilization
-
-### Reliability
- No cold starts between tenants
- Built-in redundancy and caching
- Simplified backup strategy
-
-### Cost Efficiency
- Pay-per-use storage pricing
- Shared infrastructure benefits
- Reduced operational overhead
-
-## Risk Mitigation
-
-### Data Loss Prevention
- Dual credential storage (Fly + database)
- Automated backup workflows to R2/S3
- Tigris built-in redundancy
-
-### Performance Degradation
- Configurable cache settings per tenant
- Monitoring and alerting on sync latency
- Fallback to volume storage if needed
-
-### Security Vulnerabilities
- Bucket-per-tenant isolation
- Regular credential rotation
- Security scanning and monitoring
-
-## Success Metrics
-
-### Technical Metrics
- Sync latency P50 < 5 seconds
- Container startup time < 5 seconds
- Zero data loss incidents
- 99.9% uptime per tenant
-
-### Business Metrics
- Reduced infrastructure costs vs volumes
- Improved user experience with faster sync
- Enhanced enterprise security posture
- Simplified operational overhead
-
-## Open Questions
-
-1. **Tigris rate limits**: What are the API limits for bucket creation?
-2. **Cost analysis**: What's the break-even point vs Fly volumes?
-3. **Regional preferences**: Should enterprise customers choose regions?
-4. **Backup retention**: How long to keep automated backups?
-
-## Implementation Checklist
-
-### Phase 1: Bucket Provisioning Service ✅ COMPLETED
- [x] **Research Tigris bucket API** - Document bucket creation and S3 API compatibility
- [x] **Create StorageClient class** - Implemented with admin credentials and comprehensive integration tests
- [x] **Test bucket creation** - Full test suite validates API integration with real Tigris environment
- [x] **Add bucket provisioning to DBOS workflow** - Integrated StorageClient with tenant_provisioning.py
-
-### Phase 2: Simplified Bucket Management ✅ COMPLETED
- [x] **Update Tenant model** with tigris_bucket_name field (replaced fly_volume_id)
- [x] **Implement bucket name storage** - Database migration and model updates completed
- [x] **Test bucket provisioning integration** - Full test suite validates workflow from tenant creation to bucket assignment
- [x] **Remove volume logic from all tests** - Complete migration from volume-based to bucket-based architecture
-
-### Phase 3: API Container Integration ✅ COMPLETED
- [x] **Update Dockerfile** to install TigrisFS binary in API container with configurable version
- [x] **Optimize tigrisfs-startup.sh** with production-ready security and reliability improvements
- [x] **Create production-ready container** with proper signal handling and mount validation
- [x] **Implement security fixes** based on Claude code review (conditional debug, credential protection)
- [x] **Add proper process supervision** with cleanup traps and error handling
- [x] **Remove debug artifacts** - Cleaned up all debug Dockerfiles and test scripts
-
-### Phase 3.5: IAM Access Key Management ✅ COMPLETED
- [x] **Research Tigris IAM API** - Documented create_policy, attach_user_policy, delete_access_key operations
- [x] **Implement bucket-scoped credential generation** - StorageClient.create_tenant_access_keys() with IAM policies
- [x] **Add comprehensive security test suite** - 5 security-focused integration tests covering all attack vectors
- [x] **Verify cross-bucket access prevention** - Scoped credentials can ONLY access their designated bucket
- [x] **Test credential lifecycle management** - Create, validate, delete, and revoke access keys
- [x] **Validate admin vs scoped credential isolation** - Different access patterns and security boundaries
- [x] **Test multi-tenant isolation** - Multiple tenants cannot access each other's buckets
-
-### Phase 3.6: Tenant Mount API Endpoints ✅ COMPLETED
- [x] **Implement GET /tenant/mount/info** - Returns mount info without exposing credentials
- [x] **Implement POST /tenant/mount/credentials** - Creates new bucket-scoped credentials for CLI mounting
- [x] **Implement DELETE /tenant/mount/credentials/{cred_id}** - Revoke specific credentials with proper cleanup
- [x] **Implement GET /tenant/mount/credentials** - List active credentials without exposing secrets
- [x] **Add TenantMountCredentials database model** - Tracks credential metadata (no secret storage)
- [x] **Create comprehensive test suite** - 28 tests covering all scenarios including multi-session support
- [x] **Implement multi-session credential flow** - Multiple active credentials per tenant supported
- [x] **Secure credential handling** - Secret keys never stored, returned once only for immediate use
- [x] **Add dependency injection for StorageClient** - Clean integration with existing API architecture
- [x] **Fix Tigris configuration for cloud service** - Added AWS environment variables to fly.template.toml
- [x] **Update tenant machine configurations** - Include AWS credentials for TigrisFS mounting with clear credential strategy
-
-**Security Test Results:**
-```
-✅ Cross-bucket access prevention - PASS
-✅ Deleted credentials access revoked - PASS
-✅ Invalid credentials rejected - PASS
-✅ Admin vs scoped credential isolation - PASS
-✅ Multiple scoped credentials isolation - PASS
-```
-
-**Implementation Details:**
- Uses Tigris IAM managed policies (create_policy + attach_user_policy)
- Bucket-scoped S3 policies with Actions: GetObject, PutObject, DeleteObject, ListBucket
- Resource ARNs limited to specific bucket: `arn:aws:s3:::bucket-name` and `arn:aws:s3:::bucket-name/*`
- Access keys follow Tigris format: `tid_` prefix with secure random suffix
- Complete cleanup on deletion removes both access keys and associated policies
-
-### Phase 4: Local Access CLI
- [x] **Design local mount CLI command** for automated rclone configuration
- [x] **Implement credential fetching** from cloud API for local setup
- [x] **Create rclone config automation** for tenant-specific bucket mounting
- [x] **Test local→cloud→container sync** with optimized cache settings
- [x] **Document local access setup** for beta users
-
-### Phase 5: Webhook Integration (Future)
- [ ] **Research Tigris webhook API** for object notifications and payload format
- [ ] **Design webhook endpoint** for real-time sync notifications
- [ ] **Implement notification handling** to trigger Basic Memory sync events
- [ ] **Test webhook delivery** and sync latency improvements
-
-## Success Metrics
- [ ] **Container startup < 5 seconds** including TigrisFS mount and Basic Memory init
- [ ] **Sync latency < 5 seconds** for local→cloud→container file changes
- [ ] **Zero data loss** during bucket provisioning and credential management
- [ ] **100% test coverage** for new TigrisBucketService and credential functions
- [ ] **Beta deployment** with internal users validating local-cloud workflow
-
-
-
-## Implementation Notes
-
-## Phase 4.1: Bidirectional Sync with rclone bisync (NEW)
-
-### Problem Statement
-During testing, we discovered that some applications (particularly Obsidian) don't detect file changes over NFS mounts. Rather than building a custom sync daemon, we can leverage `rclone bisync` - rclone's built-in bidirectional synchronization feature.
-
-### Solution: rclone bisync
-Use rclone's proven bidirectional sync instead of custom implementation:
-
-**Core Architecture:**
-```bash
-# rclone bisync handles all the complexity
-rclone bisync ~/basic-memory-{tenant_id} basic-memory-{tenant_id}:{bucket_name} \
-  --create-empty-src-dirs \
-  --conflict-resolve newer \
-  --resilient \
-  --check-access
-```
-
-**Key Benefits:**
- ✅ **Battle-tested**: Production-proven rclone functionality
- ✅ **MIT licensed**: Open source with permissive licensing
- ✅ **No custom code**: Zero maintenance burden for sync logic
- ✅ **Built-in safety**: max-delete protection, conflict resolution
- ✅ **Simple installation**: Works with Homebrew rclone (no FUSE needed)
- ✅ **File watcher compatible**: Works with Obsidian and all applications
- ✅ **Offline support**: Can work offline and sync when connected
-
-### bisync Conflict Resolution Options
-
-**Built-in conflict strategies:**
-```bash
--conflict-resolve none     # Keep both files with .conflict suffixes (safest)
--conflict-resolve newer    # Always pick the most recently modified file
--conflict-resolve larger   # Choose based on file size
--conflict-resolve path1    # Always prefer local changes
--conflict-resolve path2    # Always prefer cloud changes
-```
-
-### Sync Profiles Using bisync
-
-**Profile configurations:**
-```python
-BISYNC_PROFILES = {
-    "safe": {
-        "conflict_resolve": "none",      # Keep both versions
-        "max_delete": 10,                # Prevent mass deletion
-        "check_access": True,            # Verify sync integrity
-        "description": "Safe mode with conflict preservation"
-    },
-    "balanced": {
-        "conflict_resolve": "newer",     # Auto-resolve to newer file
-        "max_delete": 25,
-        "check_access": True,
-        "description": "Balanced mode (recommended default)"
-    },
-    "fast": {
-        "conflict_resolve": "newer",
-        "max_delete": 50,
-        "check_access": False,           # Skip verification for speed
-        "description": "Fast mode for rapid iteration"
-    }
-}
-```
-
-### CLI Commands
-
-**Manual sync commands:**
-```bash
-basic-memory cloud bisync                    # Manual bidirectional sync
-basic-memory cloud bisync --dry-run          # Preview changes
-basic-memory cloud bisync --profile safe     # Use specific profile
-basic-memory cloud bisync --resync           # Force full baseline resync
-```
-
-**Watch mode (Step 1):**
-```bash
-basic-memory cloud bisync --watch            # Long-running process, sync every 60s
-basic-memory cloud bisync --watch --interval 30s  # Custom interval
-```
-
-**System integration (Step 2 - Future):**
-```bash
-basic-memory cloud bisync-service install    # Install as system service
-basic-memory cloud bisync-service start      # Start background service
-basic-memory cloud bisync-service status     # Check service status
-```
-
-### Implementation Strategy
-
-**Phase 4.1.1: Core bisync Implementation**
- [ ] Implement `run_bisync()` function wrapping rclone bisync
- [ ] Add profile-based configuration (safe/balanced/fast)
- [ ] Create conflict resolution and safety options
- [ ] Test with sample files and conflict scenarios
-
-**Phase 4.1.2: Watch Mode**
- [ ] Add `--watch` flag for continuous sync
- [ ] Implement configurable sync intervals
- [ ] Add graceful shutdown and signal handling
- [ ] Create status monitoring and progress indicators
-
-**Phase 4.1.3: User Experience**
- [ ] Add conflict reporting and resolution guidance
- [ ] Implement dry-run preview functionality
- [ ] Create troubleshooting and diagnostic commands
- [ ] Add filtering configuration (.gitignore-style)
-
-**Phase 4.1.4: System Integration (Future)**
- [ ] Generate platform-specific service files (launchd/systemd)
- [ ] Add service management commands
- [ ] Implement automatic startup and recovery
- [ ] Create monitoring and logging integration
-
-### Technical Implementation
-
-**Core bisync wrapper:**
-```python
-def run_bisync(
-    tenant_id: str,
-    bucket_name: str,
-    profile: str = "balanced",
-    dry_run: bool = False
-) -> bool:
-    """Run rclone bisync with specified profile."""
-
-    local_path = Path.home() / f"basic-memory-{tenant_id}"
-    remote_path = f"basic-memory-{tenant_id}:{bucket_name}"
-    profile_config = BISYNC_PROFILES[profile]
-
-    cmd = [
-        "rclone", "bisync",
-        str(local_path), remote_path,
-        "--create-empty-src-dirs",
-        "--resilient",
-        f"--conflict-resolve={profile_config['conflict_resolve']}",
-        f"--max-delete={profile_config['max_delete']}",
-        "--filters-file", "~/.basic-memory/bisync-filters.txt"
-    ]
-
-    if profile_config.get("check_access"):
-        cmd.append("--check-access")
-
-    if dry_run:
-        cmd.append("--dry-run")
-
-    return subprocess.run(cmd, check=True).returncode == 0
-```
-
-**Default filter file (~/.basic-memory/bisync-filters.txt):**
-```
- .DS_Store
- .git/**
- __pycache__/**
- *.pyc
- .pytest_cache/**
- node_modules/**
- .conflict-*
- Thumbs.db
- desktop.ini
-```
-
-**Advantages Over Custom Daemon:**
- ✅ **Zero maintenance**: No custom sync logic to debug/maintain
- ✅ **Production proven**: Used by thousands in production
- ✅ **Safety features**: Built-in max-delete, conflict handling, recovery
- ✅ **Filtering**: Advanced exclude patterns and rules
- ✅ **Performance**: Optimized for various storage backends
- ✅ **Community support**: Extensive documentation and community
-
-## Phase 4.2: NFS Mount Support (Direct Access)
-
-### Solution: rclone nfsmount
-Keep the existing NFS mount functionality for users who prefer direct file access:
-
-**Core Architecture:**
-```bash
-# rclone nfsmount provides transparent file access
-rclone nfsmount basic-memory-{tenant_id}:{bucket_name} ~/basic-memory-{tenant_id} \
-  --vfs-cache-mode writes \
-  --dir-cache-time 10s \
-  --daemon
-```
-
-**Key Benefits:**
- ✅ **Real-time access**: Files appear immediately as they're created/modified
- ✅ **Transparent**: Works with any application that reads/writes files
- ✅ **Low latency**: Direct access without sync delays
- ✅ **Simple**: No periodic sync commands needed
- ✅ **Homebrew compatible**: Works with Homebrew rclone (no FUSE required)
-
-**Limitations:**
- ❌ **File watcher compatibility**: Some apps (Obsidian) don't detect changes over NFS
- ❌ **Network dependency**: Requires active connection to cloud storage
- ❌ **Potential conflicts**: Simultaneous edits from multiple locations can cause issues
-
-### Mount Profiles (Existing)
-
-**Already implemented profiles from SPEC-7 testing:**
-```python
-MOUNT_PROFILES = {
-    "fast": {
-        "cache_time": "5s",
-        "poll_interval": "3s",
-        "description": "Ultra-fast development (5s sync)"
-    },
-    "balanced": {
-        "cache_time": "10s",
-        "poll_interval": "5s",
-        "description": "Fast development (10-15s sync, recommended)"
-    },
-    "safe": {
-        "cache_time": "15s",
-        "poll_interval": "10s",
-        "description": "Conflict-aware mount with backup",
-        "extra_args": ["--conflict-suffix", ".conflict-{DateTimeExt}"]
-    }
-}
-```
-
-### CLI Commands (Existing)
-
-**Mount commands already implemented:**
-```bash
-basic-memory cloud mount                     # Mount with balanced profile
-basic-memory cloud mount --profile fast     # Ultra-fast caching
-basic-memory cloud mount --profile safe     # Conflict detection
-basic-memory cloud unmount                  # Clean unmount
-basic-memory cloud mount-status             # Show mount status
-```
-
-## User Choice: Mount vs Bisync
-
-### When to Use Each Approach
-
-| Use Case | Recommended Solution | Why |
-|----------|---------------------|-----|
-| **Obsidian users** | `bisync` | File watcher support for live preview |
-| **CLI/vim/emacs users** | `mount` | Direct file access, lower latency |
-| **Offline work** | `bisync` | Can work offline, sync when connected |
-| **Real-time collaboration** | `mount` | Immediate visibility of changes |
-| **Multiple machines** | `bisync` | Better conflict handling |
-| **Single machine** | `mount` | Simpler, more transparent |
-| **Development work** | Either | Both work well, user preference |
-| **Large files** | `mount` | Streaming access vs full download |
-
-### Installation Simplicity
-
-**Both approaches now use simple Homebrew installation:**
-```bash
-# Single installation command for both approaches
-brew install rclone
-
-# No macFUSE, no system modifications needed
-# Works immediately with both mount and bisync
-```
-
-### Implementation Status
-
-**Phase 4.1: bisync** (NEW)
- [ ] Implement bisync command wrapper
- [ ] Add watch mode with configurable intervals
- [ ] Create conflict resolution workflows
- [ ] Add filtering and safety options
-
-**Phase 4.2: mount** (EXISTING - ✅ IMPLEMENTED)
- [x] NFS mount commands with profile support
- [x] Mount management and cleanup
- [x] Process monitoring and health checks
- [x] Credential integration with cloud API
-
-**Both approaches share:**
- [x] Credential management via cloud API
- [x] Secure rclone configuration
- [x] Tenant isolation and bucket scoping
- [x] Simple Homebrew rclone installation
-
-
-Key Features:
-
-1. Cross-Platform rclone Installation (rclone_installer.py):
- macOS: Homebrew → official script fallback
- Linux: snap → apt → official script fallback
- Windows: winget → chocolatey → scoop fallback
- Automatic version detection and verification
-
-2. Smart rclone Configuration (rclone_config.py):
- Automatic tenant-specific config generation
- Three optimized mount profiles from your SPEC-7 testing:
- fast: 5s sync (ultra-performance)
- balanced: 10-15s sync (recommended default)
- safe: 15s sync + conflict detection
- Backup existing configs before modification
-
-3. Robust Mount Management (mount_commands.py):
- Automatic tenant credential generation
- Mount path management (~/basic-memory-{tenant-id})
- Process lifecycle management (prevent duplicate mounts)
- Orphaned process cleanup
- Mount verification and health checking
-
-4. Clean Architecture (api_client.py):
- Separated API client to avoid circular imports
- Reuses existing authentication infrastructure
- Consistent error handling and logging
-
-User Experience:
-
-One-Command Setup:
-basic-memory cloud setup
-```bash 
-# 1. Installs rclone automatically
-# 2. Authenticates with existing login
-# 3. Generates secure credentials  
-# 4. Configures rclone
-# 5. Performs initial mount
-```
-
-Profile-Based Mounting:
-basic-memory cloud mount --profile fast      # 5s sync
-basic-memory cloud mount --profile balanced  # 15s sync (default)
-basic-memory cloud mount --profile safe      # conflict detection
-
-Status Monitoring:
-basic-memory cloud mount-status
-```bash 
-# Shows: tenant info, mount path, sync profile, rclone processes
-```
-### local mount api 
-
-Endpoint 1: Get Tenant Info for user
-Purpose: Get tenant details for mounting
- pass in jwt
- service returns mount info
-
-**✅ IMPLEMENTED API Specification:**
-
-**Endpoint 1: GET /tenant/mount/info**
- Purpose: Get tenant mount information without exposing credentials
- Authentication: JWT token (tenant_id extracted from claims)
-
-Request:
-```
-GET /tenant/mount/info
-Authorization: Bearer {jwt_token}
-```
-
-Response:
-```json
-{
-    "tenant_id": "434252dd-d83b-4b20-bf70-8a950ff875c4",
-    "bucket_name": "basic-memory-434252dd",
-    "has_credentials": true,
-    "credentials_created_at": "2025-09-22T16:48:50.414694"
-}
-```
-
-**Endpoint 2: POST /tenant/mount/credentials**
- Purpose: Generate NEW bucket-scoped S3 credentials for rclone mounting
- Authentication: JWT token (tenant_id extracted from claims)
- Multi-session: Creates new credentials without revoking existing ones
-
-Request:
-```
-POST /tenant/mount/credentials
-Authorization: Bearer {jwt_token}
-Content-Type: application/json
-```
-*Note: No request body needed - tenant_id extracted from JWT*
-
-Response:
-```json
-{
-    "tenant_id": "434252dd-d83b-4b20-bf70-8a950ff875c4",
-    "bucket_name": "basic-memory-434252dd",
-    "access_key": "test_access_key_12345",
-    "secret_key": "test_secret_key_abcdef",
-    "endpoint_url": "https://fly.storage.tigris.dev",
-    "region": "auto"
-}
-```
-
-**🔒 Security Notes:**
- Secret key returned ONCE only - never stored in database
- Credentials are bucket-scoped (cannot access other tenants' buckets)
- Multiple active credentials supported per tenant (work laptop + personal machine)
-
-Implementation Notes
-
-Security:
- Both endpoints require JWT authentication
- Extract tenant_id from JWT claims (not request body)
- Generate scoped credentials (not admin credentials)
- Credentials should have bucket-specific access only
-
-Integration Points:
- Use your existing StorageClient from SPEC-8 implementation
- Leverage existing JWT middleware for tenant extraction
- Return same credential format as your Tigris bucket provisioning
-
-Error Handling:
- 401 if not authenticated
- 403 if tenant doesn't exist
- 500 if credential generation fails
-
-**🔄 Design Decisions:**
-
-1. **Secure Credential Flow (No Secret Storage)**
-
-Based on CLI flow analysis, we follow security best practices:
- ✅ API generates both access_key + secret_key via Tigris IAM
- ✅ Returns both in API response for immediate use
- ✅ CLI uses credentials immediately to configure rclone
- ✅ Database stores only metadata (access_key + policy_arn for cleanup)
- ✅ rclone handles secure local credential storage
- ❌ **Never store secret_key in database (even encrypted)**
-
-2. **CLI Credential Flow**
-```bash
-# CLI calls API
-POST /tenant/mount/credentials → {access_key, secret_key, ...}
-
-# CLI immediately configures rclone
-rclone config create basic-memory-{tenant_id} s3 \
-  access_key_id={access_key} \
-  secret_access_key={secret_key} \
-  endpoint=https://fly.storage.tigris.dev
-
-# Database tracks metadata only
-INSERT INTO tenant_mount_credentials (tenant_id, access_key, policy_arn, ...)
-```
-
-3. **Multiple Sessions Supported**
-
- Users can have multiple active credential sets (work laptop, personal machine, etc.)
- Each credential generation creates a new Tigris access key
- List active credentials via API (shows access_key but never secret)
-
-4. **Failure Handling & Cleanup**
-
- **Happy Path**: Credentials created → Used immediately → rclone configured
- **Orphaned Credentials**: Background job revokes unused credentials
- **API Failure Recovery**: Retry Tigris deletion with stored policy_arn
- **Status Tracking**: Track tigris_deletion_status (pending/completed/failed)
-
-5. **Event Sourcing & Audit**
-
- MountCredentialCreatedEvent
- MountCredentialRevokedEvent
- MountCredentialOrphanedEvent (for cleanup)
- Full audit trail for security compliance
-
-6. **Tenant/Bucket Validation**
-
- Verify tenant exists and has valid bucket before credential generation
- Use existing StorageClient to validate bucket access
- Prevent credential generation for inactive/invalid tenants
-
-📋 **Implemented API Endpoints:**
-
-```
-✅ IMPLEMENTED:
-GET    /tenant/mount/info                    # Get tenant/bucket info (no credentials exposed)
-POST   /tenant/mount/credentials             # Generate new credentials (returns secret once)
-GET    /tenant/mount/credentials             # List active credentials (no secrets)
-DELETE /tenant/mount/credentials/{cred_id}   # Revoke specific credentials
-```
-
-**API Implementation Status:**
- ✅ **GET /tenant/mount/info**: Returns tenant_id, bucket_name, has_credentials, credentials_created_at
- ✅ **POST /tenant/mount/credentials**: Creates new bucket-scoped access keys, returns access_key + secret_key once
- ✅ **GET /tenant/mount/credentials**: Lists active credentials without exposing secret keys
- ✅ **DELETE /tenant/mount/credentials/{cred_id}**: Revokes specific credentials with proper Tigris IAM cleanup
- ✅ **Multi-session support**: Multiple active credentials per tenant (work laptop + personal machine)
- ✅ **Security**: Secret keys never stored in database, returned once only for immediate use
- ✅ **Comprehensive test suite**: 28 tests covering all scenarios including error handling and multi-session flows
- ✅ **Dependency injection**: Clean integration with existing FastAPI architecture
- ✅ **Production-ready configuration**: Tigris credentials properly configured for tenant machines
-
-🗄️ **Secure Database Schema:**
-
-```sql
-CREATE TABLE tenant_mount_credentials (
-  id UUID PRIMARY KEY,
-  tenant_id UUID REFERENCES tenant(id),
-  access_key VARCHAR(255) NOT NULL,
-  -- secret_key REMOVED - never store secrets (security best practice)
-  policy_arn VARCHAR(255) NOT NULL,           -- For Tigris IAM cleanup
-  tigris_deletion_status VARCHAR(20) DEFAULT 'pending',  -- Track cleanup
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW(),
-  revoked_at TIMESTAMP NULL,
-  last_used_at TIMESTAMP NULL,               -- Track usage for orphan cleanup
-  description VARCHAR(255) DEFAULT 'CLI mount credentials'
-);
-```
-
-**Security Benefits:**
- ✅ Database breach cannot expose secrets
- ✅ Follows "secrets don't persist" security principle
- ✅ Meets compliance requirements (SOC2, etc.)
- ✅ Reduced attack surface
- ✅ CLI gets credentials once and stores securely via rclone
@@ -1,196 +0,0 @@
---
-title: 'SPEC-9: Signed Header Tenant Information'
-type: spec
-permalink: specs/spec-9-signed-header-tenant-information
-tags:
- authentication
- tenant-isolation
- proxy
- security
- mcp
---
-
-# SPEC-9: Signed Header Tenant Information
-
-## Why
-
-WorkOS JWT templates don't work with MCP's dynamic client registration requirement, preventing us from getting tenant information directly in JWT tokens. We need an alternative secure method to pass tenant context from the Cloud Proxy Service to tenant instances.
-
-**Problem Context:**
- MCP spec requires dynamic client registration
- WorkOS JWT templates only apply to statically configured clients
- Without tenant information, we can't properly route requests or isolate tenant data
- Current JWT tokens only contain standard OIDC claims (sub, email, etc.)
-
-**Affected Areas:**
- Cloud Proxy Service (`apps/cloud`) - request forwarding
- Tenant API instances (`apps/api`) - tenant context validation
- MCP Gateway (`apps/mcp`) - authentication flow
- Overall tenant isolation security model
-
-## What
-
-Implement HMAC-signed headers that the Cloud Proxy Service adds when forwarding requests to tenant instances. This provides secure, tamper-proof tenant information without relying on JWT custom claims.
-
-**Components:**
- Header signing utility in Cloud Proxy Service
- Header validation middleware in Tenant API instances
- Shared secret configuration across services
- Fallback mechanisms for development and error cases
-
-## How (High Level)
-
-### 1. Header Format
-Add these signed headers to all proxied requests:
-```
-X-BM-Tenant-ID: {tenant_id}
-X-BM-Timestamp: {unix_timestamp}
-X-BM-Signature: {hmac_sha256_signature}
-```
-
-### 2. Signature Algorithm
-```python
-# Canonical message format
-message = f"{tenant_id}:{timestamp}"
-
-# HMAC-SHA256 signature
-signature = hmac.new(
-    key=shared_secret.encode('utf-8'),
-    msg=message.encode('utf-8'),
-    digestmod=hashlib.sha256
-).hexdigest()
-```
-
-### 3. Implementation Flow
-
-#### Cloud Proxy Service (`apps/cloud`)
-1. Extract `tenant_id` from authenticated user profile
-2. Generate timestamp and canonical message
-3. Sign message with shared secret
-4. Add headers to request before forwarding to tenant instance
-
-#### Tenant API Instances (`apps/api`)
-1. Middleware validates headers on all incoming requests
-2. Extract tenant_id, timestamp from headers
-3. Verify timestamp is within acceptable window (5 minutes)
-4. Recompute signature and compare in constant time
-5. If valid, make tenant context available to Basic Memory tools
-
-### 4. Security Properties
- **Authenticity**: Only services with shared secret can create valid signatures
- **Integrity**: Header tampering invalidates signature
- **Replay Protection**: Timestamp prevents reuse of old signatures
- **Non-repudiation**: Each request is cryptographically tied to specific tenant
-
-### 5. Configuration
-```bash
-# Shared across Cloud Proxy and Tenant instances
-BM_TENANT_HEADER_SECRET=randomly-generated-256-bit-secret
-
-# Tenant API configuration
-BM_TENANT_HEADER_VALIDATION=true  # true (production) | false (dev only)
-```
-
-## How to Evaluate
-
-### Unit Tests
- [ ] Header signing utility generates correct signatures
- [ ] Header validation correctly accepts/rejects signatures
- [ ] Timestamp validation within acceptable windows
- [ ] Constant-time signature comparison prevents timing attacks
-
-### Integration Tests
- [ ] End-to-end request flow from MCP client → proxy → tenant
- [ ] Tenant isolation verified with signed headers
- [ ] Error handling for missing/invalid headers
- [ ] Disabled validation in development environment
-
-### Security Validation
- [ ] Shared secret rotation procedure
- [ ] Header tampering detection
- [ ] Clock skew tolerance testing
- [ ] Performance impact measurement
-
-### Production Readiness
- [ ] Logging and monitoring of header validation
- [ ] Graceful degradation for header validation failures
- [ ] Documentation for secret management
- [ ] Deployment configuration templates
-
-## Implementation Notes
-
-### Shared Secret Management
- Generate cryptographically secure 256-bit secret
- Same secret deployed to Cloud Proxy and all Tenant instances
- Consider secret rotation strategy for production
-
-### Error Handling
-```python
-# Strict mode (production)
-if not validate_headers(request):
-    raise HTTPException(status_code=401, detail="Invalid tenant headers")
-
-# Fallback mode (development)
-if not validate_headers(request):
-    logger.warning("Invalid headers, falling back to default tenant")
-    tenant_id = "default"
-```
-
-### Performance Considerations
- HMAC-SHA256 computation is fast (~microseconds)
- Headers add ~200 bytes to each request
- Validation happens once per request in middleware
-
-## Benefits
-
-✅ **Works with MCP dynamic client registration** - No dependency on JWT custom claims
-✅ **Simple and reliable** - Standard HMAC signature approach
-✅ **Secure by design** - Cryptographic authenticity and integrity
-✅ **Infrastructure controlled** - No external service dependencies
-✅ **Easy to implement** - Clear signature algorithm and validation
-
-## Trade-offs
-
-⚠️ **Shared secret management** - Need secure distribution and rotation
-⚠️ **Clock synchronization** - Timestamp validation requires reasonably synced clocks
-⚠️ **Header visibility** - Headers visible in logs (tenant_id not sensitive)
-⚠️ **Additional complexity** - More moving parts in proxy forwarding
-
-## Implementation Tasks
-
-### Cloud Service (Header Signing)
- [ ] Create `utils/header_signing.py` with HMAC-SHA256 signing function
- [ ] Add `bm_tenant_header_secret` to Cloud service configuration
- [ ] Update `ProxyService.forward_request()` to call signing utility
- [ ] Add signed headers (X-BM-Tenant-ID, X-BM-Timestamp, X-BM-Signature)
-
-### Tenant API (Header Validation)
- [ ] Create `utils/header_validation.py` with signature verification
- [ ] Add `bm_tenant_header_secret` to API service configuration
- [ ] Create `TenantHeaderValidationMiddleware` class
- [ ] Add middleware to FastAPI app (before other middleware)
- [ ] Skip validation for `/health` endpoint
- [ ] Store validated tenant_id in request.state
-
-### Testing
- [ ] Unit test for header signing utility
- [ ] Unit test for header validation utility
- [ ] Integration test for proxy → tenant flow
- [ ] Test invalid/missing header handling
- [ ] Test timestamp window validation
- [ ] Test signature tampering detection
-
-### Configuration & Deployment
- [ ] Update `.env.example` with BM_TENANT_HEADER_SECRET
- [ ] Generate secure 256-bit secret for production
- [ ] Update Fly.io secrets for both services
- [ ] Document secret rotation procedure
-
-## Status
-
- [x] **Specification Complete** - Design finalized and documented
- [ ] **Implementation Started** - Header signing utility development
- [ ] **Cloud Proxy Updated** - ProxyService adds signed headers
- [ ] **Tenant Validation Added** - Middleware validates headers
- [ ] **Testing Complete** - All validation criteria met
- [ ] **Production Deployed** - Live with tenant isolation via headers
@@ -1,390 +0,0 @@
---
-title: 'SPEC-9-1 Follow-Ups: Conflict, Sync, and Observability'
-type: tasklist
-permalink: specs/spec-9-follow-ups-conflict-sync-and-observability
-related: specs/spec-9-multi-project-bisync
-status: revised
-revision_date: 2025-10-03
---
-
-# SPEC-9-1 Follow-Ups: Conflict, Sync, and Observability
-
-**REVISED 2025-10-03:** Simplified to leverage rclone built-ins instead of custom conflict handling.
-
-**Context:** SPEC-9 delivered multi-project bidirectional sync and a unified CLI. This follow-up focuses on **observability and safety** using rclone's built-in capabilities rather than reinventing conflict handling.
-
-**Design Philosophy: "Be Dumb Like Git"**
- Let rclone bisync handle conflict detection (it already does this)
- Make conflicts visible and recoverable, don't prevent them
- Cloud is always the winner on conflict (cloud-primary model)
- Users who want version history can just use Git locally in their sync directory
-
-**What Changed from Original Version:**
- **Replaced:** Custom `.bmmeta` sidecars → Use rclone's `.bisync/` state tracking
- **Replaced:** Custom conflict detection → Use rclone bisync 3-way merge
- **Replaced:** Tombstone files → rclone delete tracking handles this
- **Replaced:** Distributed lease → Local process lock only (document multi-device warning)
- **Replaced:** S3 versioning service → Users just use Git locally if they want history
- **Deferred:** SPEC-14 Git integration → Postponed to teams/multi-user features
-
-## ✅ Now 
- [ ] **Local process lock**: Prevent concurrent bisync runs on same device (`~/.basic-memory/sync.lock`)
- [ ] **Structured sync reports**: Parse rclone bisync output into JSON reports (creates/updates/deletes/conflicts, bytes, duration); `bm sync --report`
- [ ] **Multi-device warning**: Document that users should not run `--watch` on multiple devices simultaneously
- [ ] **Version control guidance**: Document pattern for users to use Git locally in their sync directory if they want version history
- [ ] **Docs polish**: cloud-mode toggle, mount↔bisync directory isolation, conflict semantics, quick start, migration guide, short demo clip/GIF
-
-## 🔜 Next
- [ ] **Observability commands**: `bm conflicts list`, `bm sync history` to view sync reports and conflicts
- [ ] **Conflict resolution UI**: `bm conflicts resolve <file>` to interactively pick winner from conflict files
- [ ] **Selective sync**: allow include/exclude by project; per-project profile (safe/balanced/fast)
-
-## 🧭 Later
- [ ] **Near real-time sync**: File watcher → targeted `rclone copy` for individual files (keep bisync as backstop)
- [ ] **Sharing / scoped tokens**: cross-tenant/project access
- [ ] **Bandwidth controls & backpressure**: policy for large repos
- [ ] **Client-side encryption (optional)**: with clear trade-offs
-
-## 📏 Acceptance criteria (for "Now" items)
- [ ] Local process lock prevents concurrent bisync runs on same device
- [ ] rclone bisync conflict files visible and documented (`file.conflict1.md`, `file.conflict2.md`)
- [ ] `bm sync --report` generates parsable JSON with sync statistics
- [ ] Documentation clearly warns about multi-device `--watch` mode
- [ ] Documentation shows users how to use Git locally for version history
-
-## What We're NOT Building (Deferred to rclone)
- ❌ Custom `.bmmeta` sidecars (rclone tracks state in `.bisync/` workdir)
- ❌ Custom conflict detection (rclone bisync already does 3-way merge detection)
- ❌ Tombstone files (S3 versioning + rclone delete tracking handles this)
- ❌ Distributed lease (low probability issue, rclone detects state divergence)
- ❌ Rename/move tracking (rclone has size+modtime heuristics built-in)
-
-## Implementation Summary
-
-**Current State (SPEC-9):**
- ✅ rclone bisync with 3 profiles (safe/balanced/fast)
- ✅ `--max-delete` safety limits (10/25/50 files)
- ✅ `--conflict-resolve=newer` for auto-resolution
- ✅ Watch mode: `bm sync --watch` (60s intervals)
- ✅ Integrity checking: `bm cloud check`
- ✅ Mount vs bisync directory isolation
-
-**What's Needed (This Spec):**
-1. **Process lock** - Simple file-based lock in `~/.basic-memory/sync.lock`
-2. **Sync reports** - Parse rclone output, save to `~/.basic-memory/sync-history/`
-3. **Documentation** - Multi-device warnings, conflict resolution workflow, Git usage pattern
-
-**User Model:**
- Cloud is always the winner on conflict (cloud-primary)
- rclone creates `.conflict` files for divergent edits
- Users who want version history just use Git in their local sync directory
- Users warned: don't run `--watch` on multiple devices
-
-## Decision Rationale & Trade-offs
-
-### Why Trust rclone Instead of Custom Conflict Handling?
-
-**rclone bisync already provides:**
- 3-way merge detection (compares local, remote, and last-known state)
- File state tracking in `.bisync/` workdir (hashes, modtimes)
- Automatic conflict file creation: `file.conflict1.md`, `file.conflict2.md`
- Rename detection via size+modtime heuristics
- Delete tracking (prevents resurrection of deleted files)
- Battle-tested with extensive edge case handling
-
-**What we'd have to build with custom approach:**
- Per-file metadata tracking (`.bmmeta` sidecars)
- 3-way diff algorithm
- Conflict detection logic
- Tombstone files for deletes
- Rename/move detection
- Testing for all edge cases
-
-**Decision:** Use what rclone already does well. Don't reinvent the wheel.
-
-### Why Let Users Use Git Locally Instead of Building Versioning?
-
-**The simplest solution: Just use Git**
-
-Users who want version history can literally just use Git in their sync directory:
-
-```bash
-cd ~/basic-memory-cloud-sync/
-git init
-git add .
-git commit -m "backup"
-
-# Push to their own GitHub if they want
-git remote add origin git@github.com:user/my-knowledge.git
-git push
-```
-
-**Why this is perfect:**
- ✅ We build nothing
- ✅ Users who want Git... just use Git
- ✅ Users who don't care... don't need to
- ✅ rclone bisync already handles sync conflicts
- ✅ Users own their data, they can version it however they want (Git, Time Machine, etc.)
-
-**What we'd have to build for S3 versioning:**
- API to enable versioning on Tigris buckets
-  - **Problem**: Tigris doesn't support S3 bucket versioning
- Restore commands: `bm cloud restore --version-id`
- Version listing: `bm cloud versions <path>`
- Lifecycle policies for version retention
- Documentation and user education
-
-**What we'd have to build for SPEC-14 Git integration:**
- Committer service (daemon watching `/app/data/`)
- Puller service (webhook handler for GitHub pushes)
- Git LFS for large files
- Loop prevention between Git ↔ bisync ↔ local
- Merge conflict handling at TWO layers (rclone + Git)
- Webhook infrastructure and monitoring
-
-**Decision:** Don't build version control. Document the pattern. "The easiest problem to solve is the one you avoid."
-
-**When to revisit:** Teams/multi-user features where server-side version control becomes necessary for collaboration.
-
-### Why No Distributed Lease?
-
-**Low probability issue:**
- Requires user to manually run `bm sync` on multiple devices at exact same time
- Most users run `--watch` on one primary device
- rclone bisync detects state divergence and fails safely
-
-**Safety nets in place:**
- Local process lock prevents concurrent runs on same device
- rclone bisync aborts if bucket state changed during sync
- S3 versioning recovers from any overwrites
- Documentation warns against multi-device `--watch`
-
-**Failure mode:**
-```bash
-# Device A and B sync simultaneously
-Device A: bm sync → succeeds
-Device B: bm sync → "Error: path has changed, run --resync"
-
-# User fixes with resync
-Device B: bm sync --resync → establishes new baseline
-```
-
-**Decision:** Document the issue, add local lock, defer distributed coordination until users report actual problems.
-
-### Cloud-Primary Conflict Model
-
-**User mental model:**
- Cloud is the source of truth (like Dropbox/iCloud)
- Local is working copy
- On conflict: cloud wins, local edits → `.conflict` file
- User manually picks winner
-
-**Why this works:**
- Simpler than bidirectional merge (no automatic resolution risk)
- Matches user expectations from Dropbox
- S3 versioning provides safety net for overwrites
- Clear recovery path: restore from S3 version if needed
-
-**Example workflow:**
-```bash
-# Edit file on Device A and Device B while offline
-# Both devices come online and sync
-
-Device A: bm sync
-# → Pushes to cloud first, becomes canonical version
-
-Device B: bm sync
-# → Detects conflict
-# → Cloud version: work/notes.md
-# → Local version: work/notes.md.conflict1
-# → User manually merges or picks winner
-
-# Restore if needed
-bm cloud restore work/notes.md --version-id abc123
-```
-
-## Implementation Details
-
-### 1. Local Process Lock
-
-```python
-# ~/.basic-memory/sync.lock
-import os
-import psutil
-from pathlib import Path
-
-class SyncLock:
-    def __init__(self):
-        self.lock_file = Path.home() / '.basic-memory' / 'sync.lock'
-
-    def acquire(self):
-        if self.lock_file.exists():
-            pid = int(self.lock_file.read_text())
-            if psutil.pid_exists(pid):
-                raise BisyncError(
-                    f"Sync already running (PID {pid}). "
-                    f"Wait for completion or kill stale process."
-                )
-            # Stale lock, remove it
-            self.lock_file.unlink()
-
-        self.lock_file.write_text(str(os.getpid()))
-
-    def release(self):
-        if self.lock_file.exists():
-            self.lock_file.unlink()
-
-    def __enter__(self):
-        self.acquire()
-        return self
-
-    def __exit__(self, *args):
-        self.release()
-
-# Usage
-with SyncLock():
-    run_rclone_bisync()
-```
-
-### 3. Sync Report Parsing
-
-```python
-# Parse rclone bisync output
-import json
-from datetime import datetime
-from pathlib import Path
-
-def parse_sync_report(rclone_output: str, duration: float, exit_code: int) -> dict:
-    """Parse rclone bisync output into structured report."""
-
-    # rclone bisync outputs lines like:
-    # "Synching Path1 /local/path with Path2 remote:bucket"
-    # "- Path1    File was copied to Path2"
-    # "Bisync successful"
-
-    report = {
-        "timestamp": datetime.now().isoformat(),
-        "duration_seconds": duration,
-        "exit_code": exit_code,
-        "success": exit_code == 0,
-        "files_created": 0,
-        "files_updated": 0,
-        "files_deleted": 0,
-        "conflicts": [],
-        "errors": []
-    }
-
-    for line in rclone_output.split('\n'):
-        if 'was copied to' in line:
-            report['files_created'] += 1
-        elif 'was updated in' in line:
-            report['files_updated'] += 1
-        elif 'was deleted from' in line:
-            report['files_deleted'] += 1
-        elif '.conflict' in line:
-            report['conflicts'].append(line.strip())
-        elif 'ERROR' in line:
-            report['errors'].append(line.strip())
-
-    return report
-
-def save_sync_report(report: dict):
-    """Save sync report to history."""
-    history_dir = Path.home() / '.basic-memory' / 'sync-history'
-    history_dir.mkdir(parents=True, exist_ok=True)
-
-    timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
-    report_file = history_dir / f'{timestamp}.json'
-
-    report_file.write_text(json.dumps(report, indent=2))
-
-# Usage in run_bisync()
-start_time = time.time()
-result = subprocess.run(bisync_cmd, capture_output=True, text=True)
-duration = time.time() - start_time
-
-report = parse_sync_report(result.stdout, duration, result.returncode)
-save_sync_report(report)
-
-if report['conflicts']:
-    console.print(f"[yellow]⚠ {len(report['conflicts'])} conflict(s) detected[/yellow]")
-    console.print("[dim]Run 'bm conflicts list' to view[/dim]")
-```
-
-### 4. User Commands
-
-```bash
-# View sync history
-bm sync history
-# → Lists recent syncs from ~/.basic-memory/sync-history/*.json
-# → Shows: timestamp, duration, files changed, conflicts, errors
-
-# View current conflicts
-bm conflicts list
-# → Scans sync directory for *.conflict* files
-# → Shows: file path, conflict versions, timestamps
-
-# Restore from S3 version
-bm cloud restore work/notes.md --version-id abc123
-# → Uses aws s3api get-object with version-id
-# → Downloads to original path
-
-bm cloud restore work/notes.md --timestamp "2025-10-03 14:30"
-# → Lists versions, finds closest to timestamp
-# → Downloads that version
-
-# List file versions
-bm cloud versions work/notes.md
-# → Uses aws s3api list-object-versions
-# → Shows: version-id, timestamp, size, author
-
-# Interactive conflict resolution
-bm conflicts resolve work/notes.md
-# → Shows both versions side-by-side
-# → Prompts: Keep local, keep cloud, merge manually, restore from S3 version
-# → Cleans up .conflict files after resolution
-```
-
-## Success Metrics & Monitoring
-
-**Phase 1 (v1) - Basic Safety:**
- [ ] Conflict detection rate < 5% of syncs (measure in telemetry)
- [ ] User can resolve conflicts within 5 minutes (UX testing)
- [ ] Documentation prevents 90% of multi-device issues
-
-**Phase 2 (v2) - Observability:**
- [ ] 80% of users check `bm sync history` when troubleshooting
- [ ] Average time to restore from S3 version < 2 minutes
- 
- [ ] Conflict resolution success rate > 95%
-
-**What to measure:**
-```python
-# Telemetry in sync reports
-{
-    "conflict_rate": conflicts / total_syncs,
-    "multi_device_collisions": count_state_divergence_errors,
-    "version_restores": count_restore_operations,
-    "avg_sync_duration": sum(durations) / count,
-    "max_delete_trips": count_max_delete_aborts
-}
-```
-
-**When to add distributed lease:**
- Multi-device collision rate > 5% of syncs
- User complaints about state divergence errors
- Evidence that local lock isn't sufficient
-
-**When to revisit Git (SPEC-14):**
- Teams feature launches (multi-user collaboration)
- Users request commit messages / audit trail
- PR-based review workflow becomes valuable
-
-## Links
- SPEC-9: `specs/spec-9-multi-project-bisync`
- SPEC-14: `specs/spec-14-cloud-git-versioning` (deferred in favor of S3 versioning)
- rclone bisync docs: https://rclone.org/bisync/
- Tigris S3 versioning: https://www.tigrisdata.com/docs/buckets/versioning/
-
---
-**Owner:** <assign>  |  **Review cadence:** weekly in standup  |  **Last updated:** 2025-10-03
@@ -1,7 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""

 # Package version - updated by release automation
-__version__ = "0.16.2"
+__version__ = "0.14.4"

 # API version for FastAPI - independent of package version
 __api_version__ = "v0"
@@ -8,7 +8,7 @@ from sqlalchemy import pool

 from alembic import context

-from basic_memory.config import ConfigManager, DatabaseBackend
+from basic_memory.config import ConfigManager

 # set config.env to "test" for pytest to prevent logging to file in utils.setup_logging()
 os.environ["BASIC_MEMORY_ENV"] = "test"
@@ -20,28 +20,12 @@ from basic_memory.models import Base  # noqa: E402
 # access to the values within the .ini file in use.
 config = context.config

-# Load app config - this will read environment variables (BASIC_MEMORY_DATABASE_BACKEND, etc.)
-# due to Pydantic's env_prefix="BASIC_MEMORY_" setting
 app_config = ConfigManager().config
+# Set the SQLAlchemy URL from our app config
+sqlalchemy_url = f"sqlite:///{app_config.database_path}"
+config.set_main_option("sqlalchemy.url", sqlalchemy_url)

-# Set the SQLAlchemy URL based on database backend configuration
-# If the URL is already set in config (e.g., from run_migrations), use that
-# Otherwise, get it from app config
-# Note: alembic.ini has a placeholder URL "driver://user:pass@localhost/dbname" that we need to override
-current_url = config.get_main_option("sqlalchemy.url")
-if not current_url or current_url == "driver://user:pass@localhost/dbname":
-    from basic_memory.db import DatabaseType
-
-    sqlalchemy_url = DatabaseType.get_db_url(
-        app_config.database_path, DatabaseType.FILESYSTEM, app_config
-    )
-
-    # For Postgres, Alembic needs synchronous driver (psycopg2), not async (asyncpg)
-    if app_config.database_backend == DatabaseBackend.POSTGRES:
-        # Convert asyncpg URL to psycopg2 URL for Alembic
-        sqlalchemy_url = sqlalchemy_url.replace("postgresql+asyncpg://", "postgresql://")
-
-    config.set_main_option("sqlalchemy.url", sqlalchemy_url)
+# print(f"Using SQLAlchemy URL: {sqlalchemy_url}")

 # Interpret the config file for Python logging.
 if config.config_file_name is not None:
@@ -1,131 +0,0 @@
-"""Add Postgres full-text search support with tsvector and GIN indexes
-
-Revision ID: 314f1ea54dc4
-Revises: e7e1f4367280
-Create Date: 2025-11-15 18:05:01.025405
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = "314f1ea54dc4"
-down_revision: Union[str, None] = "e7e1f4367280"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    """Add PostgreSQL full-text search support.
-
-    This migration:
-    1. Creates search_index table for Postgres (SQLite uses FTS5 virtual table)
-    2. Adds generated tsvector column for full-text search
-    3. Creates GIN index on the tsvector column for fast text queries
-    4. Creates GIN index on metadata JSONB column for fast containment queries
-
-    Note: These changes only apply to Postgres. SQLite continues to use FTS5 virtual tables.
-    """
-    # Check if we're using Postgres
-    connection = op.get_bind()
-    if connection.dialect.name == "postgresql":
-        # Create search_index table for Postgres
-        # For SQLite, this is a FTS5 virtual table created elsewhere
-        from sqlalchemy.dialects.postgresql import JSONB
-
-        op.create_table(
-            "search_index",
-            sa.Column("id", sa.Integer(), nullable=False),  # Entity IDs are integers
-            sa.Column("project_id", sa.Integer(), nullable=False),  # Multi-tenant isolation
-            sa.Column("title", sa.Text(), nullable=True),
-            sa.Column("content_stems", sa.Text(), nullable=True),
-            sa.Column("content_snippet", sa.Text(), nullable=True),
-            sa.Column("permalink", sa.String(), nullable=True),  # Nullable for non-markdown files
-            sa.Column("file_path", sa.String(), nullable=True),
-            sa.Column("type", sa.String(), nullable=True),
-            sa.Column("from_id", sa.Integer(), nullable=True),  # Relation IDs are integers
-            sa.Column("to_id", sa.Integer(), nullable=True),  # Relation IDs are integers
-            sa.Column("relation_type", sa.String(), nullable=True),
-            sa.Column("entity_id", sa.Integer(), nullable=True),  # Entity IDs are integers
-            sa.Column("category", sa.String(), nullable=True),
-            sa.Column("metadata", JSONB(), nullable=True),  # Use JSONB for Postgres
-            sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
-            sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
-            sa.PrimaryKeyConstraint(
-                "id", "type", "project_id"
-            ),  # Composite key: id can repeat across types
-            sa.ForeignKeyConstraint(
-                ["project_id"],
-                ["project.id"],
-                name="fk_search_index_project_id",
-                ondelete="CASCADE",
-            ),
-            if_not_exists=True,
-        )
-
-        # Create index on project_id for efficient multi-tenant queries
-        op.create_index(
-            "ix_search_index_project_id",
-            "search_index",
-            ["project_id"],
-            unique=False,
-        )
-
-        # Create unique partial index on permalink for markdown files
-        # Non-markdown files don't have permalinks, so we use a partial index
-        op.execute("""
-            CREATE UNIQUE INDEX uix_search_index_permalink_project
-            ON search_index (permalink, project_id)
-            WHERE permalink IS NOT NULL
-        """)
-
-        # Add tsvector column as a GENERATED ALWAYS column
-        # This automatically updates when title or content_stems change
-        op.execute("""
-            ALTER TABLE search_index
-            ADD COLUMN textsearchable_index_col tsvector
-            GENERATED ALWAYS AS (
-                to_tsvector('english',
-                    coalesce(title, '') || ' ' ||
-                    coalesce(content_stems, '')
-                )
-            ) STORED
-        """)
-
-        # Create GIN index on tsvector column for fast full-text search
-        op.create_index(
-            "idx_search_index_fts",
-            "search_index",
-            ["textsearchable_index_col"],
-            unique=False,
-            postgresql_using="gin",
-        )
-
-        # Create GIN index on metadata JSONB for fast containment queries
-        # Using jsonb_path_ops for smaller index size and better performance
-        op.execute("""
-            CREATE INDEX idx_search_index_metadata_gin
-            ON search_index
-            USING GIN (metadata jsonb_path_ops)
-        """)
-
-
-def downgrade() -> None:
-    """Remove PostgreSQL full-text search support."""
-    connection = op.get_bind()
-    if connection.dialect.name == "postgresql":
-        # Drop indexes first
-        op.execute("DROP INDEX IF EXISTS idx_search_index_metadata_gin")
-        op.drop_index("idx_search_index_fts", table_name="search_index")
-        op.execute("DROP INDEX IF EXISTS uix_search_index_permalink_project")
-        op.drop_index("ix_search_index_project_id", table_name="search_index")
-
-        # Drop the generated column
-        op.execute("ALTER TABLE search_index DROP COLUMN IF EXISTS textsearchable_index_col")
-
-        # Drop the search_index table
-        op.drop_table("search_index")
@@ -21,12 +21,6 @@ depends_on: Union[str, Sequence[str], None] = None

 def upgrade() -> None:
    # ### commands auto generated by Alembic - please adjust! ###
-
-    # SQLite FTS5 virtual table handling is SQLite-specific
-    # For Postgres, search_index is a regular table managed by ORM
-    connection = op.get_bind()
-    is_sqlite = connection.dialect.name == "sqlite"
-
    op.create_table(
        "project",
        sa.Column("id", sa.Integer(), nullable=False),
@@ -61,9 +55,7 @@ def upgrade() -> None:
        batch_op.add_column(sa.Column("project_id", sa.Integer(), nullable=False))
        batch_op.drop_index(
            "uix_entity_permalink",
-            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL")
-            if is_sqlite
-            else None,
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
        )
        batch_op.drop_index("ix_entity_file_path")
        batch_op.create_index(batch_op.f("ix_entity_file_path"), ["file_path"], unique=False)
@@ -75,16 +67,12 @@ def upgrade() -> None:
            "uix_entity_permalink_project",
            ["permalink", "project_id"],
            unique=True,
-            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL")
-            if is_sqlite
-            else None,
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
        )
        batch_op.create_foreign_key("fk_entity_project_id", "project", ["project_id"], ["id"])

    # drop the search index table. it will be recreated
-    # Only drop for SQLite - Postgres uses regular table managed by ORM
-    if is_sqlite:
-        op.drop_table("search_index")
+    op.drop_table("search_index")

    # ### end Alembic commands ###

@@ -25,51 +25,43 @@ def upgrade() -> None:
    The UNIQUE constraint prevents multiple projects from having is_default=FALSE,
    which breaks project creation when the service sets is_default=False.

-    SQLite: Recreate the table without the constraint (no ALTER TABLE support)
-    Postgres: Use ALTER TABLE to drop the constraint directly
+    Since SQLite doesn't support dropping specific constraints easily, we'll
+    recreate the table without the problematic constraint.
    """
-    connection = op.get_bind()
-    is_sqlite = connection.dialect.name == "sqlite"
+    # For SQLite, we need to recreate the table without the UNIQUE constraint
+    # Create a new table without the UNIQUE constraint on is_default
+    op.create_table(
+        "project_new",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("permalink", sa.String(), nullable=False),
+        sa.Column("path", sa.String(), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("is_default", sa.Boolean(), nullable=True),  # No UNIQUE constraint!
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("name"),
+        sa.UniqueConstraint("permalink"),
+    )

-    if is_sqlite:
-        # For SQLite, we need to recreate the table without the UNIQUE constraint
-        # Create a new table without the UNIQUE constraint on is_default
-        op.create_table(
-            "project_new",
-            sa.Column("id", sa.Integer(), nullable=False),
-            sa.Column("name", sa.String(), nullable=False),
-            sa.Column("description", sa.Text(), nullable=True),
-            sa.Column("permalink", sa.String(), nullable=False),
-            sa.Column("path", sa.String(), nullable=False),
-            sa.Column("is_active", sa.Boolean(), nullable=False),
-            sa.Column("is_default", sa.Boolean(), nullable=True),  # No UNIQUE constraint!
-            sa.Column("created_at", sa.DateTime(), nullable=False),
-            sa.Column("updated_at", sa.DateTime(), nullable=False),
-            sa.PrimaryKeyConstraint("id"),
-            sa.UniqueConstraint("name"),
-            sa.UniqueConstraint("permalink"),
-        )
+    # Copy data from old table to new table
+    op.execute("INSERT INTO project_new SELECT * FROM project")

-        # Copy data from old table to new table
-        op.execute("INSERT INTO project_new SELECT * FROM project")
+    # Drop the old table
+    op.drop_table("project")

-        # Drop the old table
-        op.drop_table("project")
+    # Rename the new table
+    op.rename_table("project_new", "project")

-        # Rename the new table
-        op.rename_table("project_new", "project")
-
-        # Recreate the indexes
-        with op.batch_alter_table("project", schema=None) as batch_op:
-            batch_op.create_index("ix_project_created_at", ["created_at"], unique=False)
-            batch_op.create_index("ix_project_name", ["name"], unique=True)
-            batch_op.create_index("ix_project_path", ["path"], unique=False)
-            batch_op.create_index("ix_project_permalink", ["permalink"], unique=True)
-            batch_op.create_index("ix_project_updated_at", ["updated_at"], unique=False)
-    else:
-        # For Postgres, we can simply drop the constraint
-        with op.batch_alter_table("project", schema=None) as batch_op:
-            batch_op.drop_constraint("project_is_default_key", type_="unique")
+    # Recreate the indexes
+    with op.batch_alter_table("project", schema=None) as batch_op:
+        batch_op.create_index("ix_project_created_at", ["created_at"], unique=False)
+        batch_op.create_index("ix_project_name", ["name"], unique=True)
+        batch_op.create_index("ix_project_path", ["path"], unique=False)
+        batch_op.create_index("ix_project_permalink", ["permalink"], unique=True)
+        batch_op.create_index("ix_project_updated_at", ["updated_at"], unique=False)


 def downgrade() -> None:
@@ -1,49 +0,0 @@
-"""Add mtime and size columns to Entity for sync optimization
-
-Revision ID: 9d9c1cb7d8f5
-Revises: a1b2c3d4e5f6
-Create Date: 2025-10-20 05:07:55.173849
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = "9d9c1cb7d8f5"
-down_revision: Union[str, None] = "a1b2c3d4e5f6"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # ### commands auto generated by Alembic - please adjust! ###
-    with op.batch_alter_table("entity", schema=None) as batch_op:
-        batch_op.add_column(sa.Column("mtime", sa.Float(), nullable=True))
-        batch_op.add_column(sa.Column("size", sa.Integer(), nullable=True))
-        batch_op.drop_constraint(batch_op.f("fk_entity_project_id"), type_="foreignkey")
-        batch_op.create_foreign_key(
-            batch_op.f("fk_entity_project_id"), "project", ["project_id"], ["id"]
-        )
-
-    # ### end Alembic commands ###
-
-
-def downgrade() -> None:
-    # ### commands auto generated by Alembic - please adjust! ###
-    with op.batch_alter_table("entity", schema=None) as batch_op:
-        batch_op.drop_constraint(batch_op.f("fk_entity_project_id"), type_="foreignkey")
-        batch_op.create_foreign_key(
-            batch_op.f("fk_entity_project_id"),
-            "project",
-            ["project_id"],
-            ["id"],
-            ondelete="CASCADE",
-        )
-        batch_op.drop_column("size")
-        batch_op.drop_column("mtime")
-
-    # ### end Alembic commands ###
@@ -21,12 +21,6 @@ depends_on: Union[str, Sequence[str], None] = None
 def upgrade() -> None:
    """Upgrade database schema to use new search index with content_stems and content_snippet."""

-    # This migration is SQLite-specific (FTS5 virtual tables)
-    # For Postgres, the search_index table is created via ORM models
-    connection = op.get_bind()
-    if connection.dialect.name != "sqlite":
-        return
-
    # First, drop the existing search_index table
    op.execute("DROP TABLE IF EXISTS search_index")

@@ -65,13 +59,6 @@ def upgrade() -> None:

 def downgrade() -> None:
    """Downgrade database schema to use old search index."""
-
-    # This migration is SQLite-specific (FTS5 virtual tables)
-    # For Postgres, the search_index table is managed via ORM models
-    connection = op.get_bind()
-    if connection.dialect.name != "sqlite":
-        return
-
    # Drop the updated search_index table
    op.execute("DROP TABLE IF EXISTS search_index")

@@ -1,37 +0,0 @@
-"""Add scan watermark tracking to Project
-
-Revision ID: e7e1f4367280
-Revises: 9d9c1cb7d8f5
-Create Date: 2025-10-20 16:42:46.625075
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = "e7e1f4367280"
-down_revision: Union[str, None] = "9d9c1cb7d8f5"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # ### commands auto generated by Alembic - please adjust! ###
-    with op.batch_alter_table("project", schema=None) as batch_op:
-        batch_op.add_column(sa.Column("last_scan_timestamp", sa.Float(), nullable=True))
-        batch_op.add_column(sa.Column("last_file_count", sa.Integer(), nullable=True))
-
-    # ### end Alembic commands ###
-
-
-def downgrade() -> None:
-    # ### commands auto generated by Alembic - please adjust! ###
-    with op.batch_alter_table("project", schema=None) as batch_op:
-        batch_op.drop_column("last_file_count")
-        batch_op.drop_column("last_scan_timestamp")
-
-    # ### end Alembic commands ###
@@ -19,27 +19,22 @@ from basic_memory.api.routers import (
    resource,
    search,
    prompt_router,
+    webdav,
 )
 from basic_memory.config import ConfigManager
-from basic_memory.services.initialization import initialize_file_sync, initialize_app
+from basic_memory.services.initialization import initialize_app, initialize_file_sync


@asynccontextmanager
 async def lifespan(app: FastAPI):  # pragma: no cover
-    """Lifecycle manager for the FastAPI app. Not called in stdio mcp mode"""
+    """Lifecycle manager for the FastAPI app."""

    app_config = ConfigManager().config
+    # Initialize app and database
    logger.info("Starting Basic Memory API")
-
+    print(f"fastapi {app_config.projects}")
    await initialize_app(app_config)

-    # Cache database connections in app state for performance
-    logger.info("Initializing database and caching connections...")
-    engine, session_maker = await db.get_or_create_db(app_config.database_path)
-    app.state.engine = engine
-    app.state.session_maker = session_maker
-    logger.info("Database connections cached in app state")
-
    logger.info(f"Sync changes enabled: {app_config.sync_changes}")
    if app_config.sync_changes:
        # start file sync task in background
@@ -76,6 +71,7 @@ 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}")
+app.include_router(webdav.router, prefix="/{project}")

 # Project resource router works accross projects
 app.include_router(project.project_resource_router)
@@ -7,5 +7,6 @@ from . import project_router as project
 from . import resource_router as resource
 from . import search_router as search
 from . import prompt_router as prompt
+from . import webdav_router as webdav

-__all__ = ["knowledge", "management", "memory", "project", "resource", "search", "prompt"]
+__all__ = ["knowledge", "management", "memory", "project", "resource", "search", "prompt", "webdav"]
@@ -10,7 +10,7 @@ from basic_memory.schemas.directory import DirectoryNode
 router = APIRouter(prefix="/directory", tags=["directory"])


-@router.get("/tree", response_model=DirectoryNode, response_model_exclude_none=True)
+@router.get("/tree", response_model=DirectoryNode)
 async def get_directory_tree(
    directory_service: DirectoryServiceDep,
    project_id: ProjectIdDep,
@@ -31,28 +31,7 @@ async def get_directory_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)
+@router.get("/list", response_model=List[DirectoryNode])
 async def list_directory(
    directory_service: DirectoryServiceDep,
    project_id: ProjectIdDep,
@@ -27,26 +27,6 @@ from basic_memory.schemas.base import Permalink, Entity

 router = APIRouter(prefix="/knowledge", tags=["knowledge"])

-
-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:
-        # Log but don't fail - this is a background task
-        logger.warning(
-            f"Background: Failed to resolve relations for entity {entity_permalink}: {e}"
-        )
-
-
 ## Create endpoints


@@ -108,12 +88,15 @@ async def create_or_update_entity(
    # 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
+    # Attempt immediate relation resolution when creating new entities
+    # This helps resolve forward references when related entities are created in the same session
    if created:
-        background_tasks.add_task(
-            resolve_relations_background, sync_service, entity.id, entity.permalink or ""
-        )
+        try:
+            await sync_service.resolve_relations()
+            logger.debug(f"Resolved relations after creating entity: {entity.permalink}")
+        except Exception as e:  # pragma: no cover
+            # Don't fail the entire request if relation resolution fails
+            logger.warning(f"Failed to resolve relations after entity creation: {e}")

    result = EntityResponse.model_validate(entity)

@@ -1,24 +1,17 @@
 """Router for project management."""

 import os
-from fastapi import APIRouter, HTTPException, Path, Body, BackgroundTasks, Response, Query
+from fastapi import APIRouter, HTTPException, Path, Body
 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.deps import ProjectServiceDep, ProjectPathDep
+from basic_memory.schemas import ProjectInfoResponse
 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
@@ -51,7 +44,7 @@ async def get_project(

    return ProjectItem(
        name=found_project.name,
-        path=normalize_project_path(found_project.path),
+        path=found_project.path,
        is_default=found_project.is_default or False,
    )

@@ -104,73 +97,6 @@ async def update_project(
        raise HTTPException(status_code=400, detail=str(e))


-# 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}")
-    sync_report = await sync_service.scan(project_config.home)
-
-    return SyncReportResponse.from_sync_report(sync_report)
-
-
 # List all available projects
@project_resource_router.get("/projects", response_model=ProjectList)
 async def list_projects(
@@ -187,7 +113,7 @@ async def list_projects(
    project_items = [
        ProjectItem(
            name=project.name,
-            path=normalize_project_path(project.path),
+            path=project.path,
            is_default=project.is_default or False,
        )
        for project in projects
@@ -200,9 +126,8 @@ async def list_projects(


 # Add a new project
-@project_resource_router.post("/projects", response_model=ProjectStatusResponse, status_code=201)
+@project_resource_router.post("/projects", response_model=ProjectStatusResponse)
 async def add_project(
-    response: Response,
    project_data: ProjectInfoRequest,
    project_service: ProjectServiceDep,
 ) -> ProjectStatusResponse:
@@ -214,38 +139,7 @@ async def add_project(
    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(
-                    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
        )
@@ -267,15 +161,11 @@ async def add_project(
 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
@@ -287,20 +177,7 @@ async def remove_project(
                status_code=404, detail=f"Project: '{name}' does not exist"
            )  # pragma: no cover

-        # Check if trying to delete the default project
-        if name == project_service.default_project:
-            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)
+        await project_service.remove_project(name)

        return ProjectStatusResponse(
            message=f"Project '{name}' removed successfully",
@@ -382,7 +259,7 @@ async def get_default_project(


 # Synchronize projects between config and database
-@project_resource_router.post("/config/sync", response_model=ProjectStatusResponse)
+@project_resource_router.post("/sync", response_model=ProjectStatusResponse)
 async def synchronize_projects(
    project_service: ProjectServiceDep,
 ) -> ProjectStatusResponse:
@@ -151,20 +151,6 @@ async def write_resource(
    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(
-                f"Error writing resource {file_path}: "
-                f"content is a dict, expected string. Keys: {list(content.keys())}"
-            )
-            raise HTTPException(
-                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")
@@ -0,0 +1,353 @@
+"""WebDAV router for basic-memory project uploads."""
+
+import os
+import shutil
+from datetime import datetime
+from pathlib import Path
+import aiofiles
+from loguru import logger
+
+from basic_memory.deps import ProjectPathDep, ProjectServiceDep
+from fastapi import APIRouter, Request, Response, HTTPException
+from fastapi.responses import StreamingResponse
+
+router = APIRouter(
+    prefix="/webdav",
+    tags=["webdav"],
+)
+
+
+async def get_project_path_or_404(project_service: ProjectServiceDep, project: str) -> Path:
+    found_project = await project_service.get_project(project)
+    if not found_project:
+        raise HTTPException(status_code=404, detail=f"Project: '{project}' does not exist")
+    return Path(found_project.path)
+
+
+async def get_project_file_path_or_404(project_path: Path, path: str) -> Path:
+    file_path = Path(project_path / path)
+    if not file_path.exists():
+        raise HTTPException(status_code=404, detail=f"File: '{path}' does not exist")
+    return file_path
+
+
+@router.api_route("/{path:path}", methods=["OPTIONS"])
+async def webdav_options(
+    path: str,
+    project: ProjectPathDep,
+    project_service: ProjectServiceDep,
+):
+    """WebDAV OPTIONS endpoint."""
+    project_path = await get_project_path_or_404(project_service, project)
+    file_path = await get_project_file_path_or_404(project_path, path)
+    return await _webdav_options(file_path)
+
+
+@router.api_route("/{path:path}", methods=["PROPFIND"])
+async def webdav_propfind(
+    path: str,
+    project: ProjectPathDep,
+    project_service: ProjectServiceDep,
+):
+    """WebDAV PROPFIND endpoint."""
+    project_path = await get_project_path_or_404(project_service, project)
+    file_path = await get_project_file_path_or_404(project_path, path)
+    return await _webdav_propfind(project, project_path, file_path)
+
+
+@router.api_route("/{path:path}", methods=["GET"])
+async def webdav_get(
+    path: str,
+    project: ProjectPathDep,
+    project_service: ProjectServiceDep,
+):
+    """WebDAV GET endpoint."""
+    project_path = await get_project_path_or_404(project_service, project)
+    file_path = await get_project_file_path_or_404(project_path, path)
+    return await _webdav_get(file_path)
+
+
+@router.api_route("/{path:path}", methods=["PUT"])
+async def webdav_put(
+    request: Request,
+    path: str,
+    project: ProjectPathDep,
+    project_service: ProjectServiceDep,
+):
+    """WebDAV PUT endpoint."""
+    project_path = await get_project_path_or_404(project_service, project)
+    file_path = Path(project_path / path)
+    return await _webdav_put(request, project, file_path)
+
+
+@router.api_route("/{path:path}", methods=["DELETE"])
+async def webdav_delete(
+    path: str,
+    project: ProjectPathDep,
+    project_service: ProjectServiceDep,
+):
+    """WebDAV DELETE endpoint."""
+    project_path = await get_project_path_or_404(project_service, project)
+    file_path = await get_project_file_path_or_404(project_path, path)
+    return await _webdav_delete(project, file_path)
+
+
+@router.api_route("/{path:path}", methods=["MKCOL"])
+async def webdav_mkcol(
+    path: str,
+    project: ProjectPathDep,
+    project_service: ProjectServiceDep,
+):
+    """WebDAV MKCOL endpoint."""
+    project_path = await get_project_path_or_404(project_service, project)
+    dir_path = Path(project_path / path)
+    return await _webdav_mkcol(project, dir_path)
+
+
+# Handle WebDAV root
+@router.api_route("/", methods=["OPTIONS", "PROPFIND"])
+async def webdav_root(
+    request: Request,
+    project: ProjectPathDep,
+    project_service: ProjectServiceDep,
+):
+    """WebDAV root endpoint."""
+    project_path = await get_project_path_or_404(project_service, project)
+    method = request.method
+    if method == "OPTIONS":
+        return await _webdav_options(project_path)
+    else:
+        return await _webdav_propfind(project, project_path, project_path)
+
+
+async def _webdav_options(file_path: Path) -> Response:
+    """Handle WebDAV OPTIONS request."""
+    file_size = file_path.stat().st_size
+    return Response(
+        status_code=204,
+        headers={
+            "DAV": "1,2",
+            "MS-Author-Via": "DAV",
+            "Allow": "OPTIONS,GET,HEAD,POST,DELETE,TRACE,PROPFIND,PROPPATCH,COPY,MOVE,LOCK,UNLOCK,PUT",
+            "Content-Length": f"{file_size}",
+        },
+    )
+
+
+async def _webdav_propfind(project: str, project_path: Path, file_path: Path) -> Response:
+    """Handle WebDAV PROPFIND request to list directory contents."""
+
+    # Calculate relative path from project root
+    try:
+        relative_path = file_path.relative_to(project_path)
+        relative_path_str = str(relative_path).replace("\\", "/")
+        if relative_path_str == ".":
+            relative_path_str = ""
+    except ValueError:
+        # file_path is not under project_path
+        relative_path_str = ""
+
+    # Build minimal PROPFIND response
+    if file_path.is_dir():
+        # Directory listing
+        href_path = (
+            f"/{project}/webdav/{relative_path_str}/"
+            if relative_path_str
+            else f"/{project}/webdav/"
+        )
+        xml_response = f"""<?xml version="1.0" encoding="utf-8"?>
+<D:multistatus xmlns:D="DAV:">
+<D:response>
+    <D:href>{href_path}</D:href>
+    <D:propstat>
+        <D:prop>
+            <D:resourcetype><D:collection/></D:resourcetype>
+            <D:displayname>{file_path.name if file_path.name else project}</D:displayname>
+        </D:prop>
+        <D:status>HTTP/1.1 200 OK</D:status>
+    </D:propstat>
+</D:response>
+"""
+
+        # Add child items
+        for child in file_path.iterdir():
+            # Calculate child relative path
+            child_relative = child.relative_to(project_path)
+            child_relative_str = str(child_relative).replace("\\", "/")
+
+            if child.is_dir():
+                child_href = f"/{project}/webdav/{child_relative_str}/"
+                xml_response += f"""<D:response>
+    <D:href>{child_href}</D:href>
+    <D:propstat>
+        <D:prop>
+            <D:resourcetype><D:collection/></D:resourcetype>
+            <D:displayname>{child.name}</D:displayname>
+        </D:prop>
+        <D:status>HTTP/1.1 200 OK</D:status>
+    </D:propstat>
+</D:response>
+"""
+            else:
+                child_href = f"/{project}/webdav/{child_relative_str}"
+                file_size = child.stat().st_size
+                xml_response += f"""<D:response>
+    <D:href>{child_href}</D:href>
+    <D:propstat>
+        <D:prop>
+            <D:resourcetype/>
+            <D:displayname>{child.name}</D:displayname>
+            <D:getcontentlength>{file_size}</D:getcontentlength>
+        </D:prop>
+        <D:status>HTTP/1.1 200 OK</D:status>
+    </D:propstat>
+</D:response>
+"""
+
+        xml_response += "</D:multistatus>"
+    else:
+        # File properties
+        href_path = f"/{project}/webdav/{relative_path_str}"
+        file_size = file_path.stat().st_size
+        xml_response = f"""<?xml version="1.0" encoding="utf-8"?>
+<D:multistatus xmlns:D="DAV:">
+<D:response>
+    <D:href>{href_path}</D:href>
+    <D:propstat>
+        <D:prop>
+            <D:resourcetype/>
+            <D:displayname>{file_path.name}</D:displayname>
+            <D:getcontentlength>{file_size}</D:getcontentlength>
+        </D:prop>
+        <D:status>HTTP/1.1 200 OK</D:status>
+    </D:propstat>
+</D:response>
+</D:multistatus>"""
+
+    return Response(content=xml_response, status_code=207, media_type="text/xml; charset=utf-8")
+
+
+async def _webdav_get(file_path: Path) -> Response:
+    """Handle WebDAV GET request to download file."""
+
+    async def file_generator():
+        async with aiofiles.open(file_path, "rb") as file:
+            while chunk := await file.read(8192):
+                yield chunk
+
+    file_size = file_path.stat().st_size
+    headers = {"Content-Length": str(file_size), "Content-Type": "application/octet-stream"}
+
+    return StreamingResponse(file_generator(), status_code=200, headers=headers)
+
+
+async def _webdav_put(request: Request, project: str, file_path: Path) -> Response:
+    """Handle WebDAV PUT request to upload file."""
+
+    # Check if file exists before writing (for correct HTTP status)
+    file_existed = file_path.exists()
+
+    # Ensure parent directory exists
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write file content
+    try:
+        async with aiofiles.open(file_path, "wb") as file:
+            async for chunk in request.stream():
+                await file.write(chunk)
+
+        # Preserve timestamps if provided in headers
+        await _preserve_file_timestamps(request, file_path)
+
+        logger.info(f"WebDAV: Uploaded file {file_path} to project {project}.")
+
+        return Response(status_code=204 if file_existed else 201)
+
+    except Exception as e:
+        logger.error(f"WebDAV: Failed to upload file {file_path}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to upload file: {e}") from e
+
+
+async def _preserve_file_timestamps(request: Request, file_path: Path) -> None:
+    """Preserve file timestamps from WebDAV headers if provided.
+
+    Supports multiple timestamp header formats:
+    - X-OC-Mtime: Unix timestamp (ownCloud/Nextcloud format)
+    - X-Timestamp: Unix timestamp
+    - X-Mtime: Unix timestamp
+    - Last-Modified: HTTP date format
+    """
+
+    # Try different header formats for modification time
+    mtime_timestamp = None
+
+    # Check for custom timestamp headers (Unix timestamp)
+    for header_name in ["X-OC-Mtime", "X-Timestamp", "X-Mtime"]:
+        if header_name in request.headers:
+            try:
+                mtime_timestamp = float(request.headers[header_name])
+                logger.debug(f"Using {header_name} timestamp: {mtime_timestamp}")
+                break
+            except (ValueError, TypeError) as e:
+                logger.warning(f"Invalid timestamp in {header_name} header: {e}")
+                continue
+
+    # Fall back to Last-Modified header if no custom timestamp found
+    if mtime_timestamp is None and "Last-Modified" in request.headers:
+        try:
+            # Parse HTTP date format
+            last_modified_str = request.headers["Last-Modified"]
+            dt = datetime.strptime(last_modified_str, "%a, %d %b %Y %H:%M:%S GMT")
+            # Replace with UTC timezone to ensure correct timestamp calculation
+            from datetime import timezone
+
+            dt = dt.replace(tzinfo=timezone.utc)
+            mtime_timestamp = dt.timestamp()
+            logger.debug(f"Using Last-Modified timestamp: {mtime_timestamp}")
+        except (ValueError, TypeError) as e:
+            logger.warning(f"Invalid Last-Modified header format: {e}")
+
+    # Apply timestamp if we found one
+    if mtime_timestamp is not None:
+        try:
+            # Use os.utime to set both access and modification times
+            # Set access time to modification time to keep them consistent
+            os.utime(file_path, (mtime_timestamp, mtime_timestamp))
+            logger.debug(f"Set file timestamps for {file_path} to {mtime_timestamp}")
+        except OSError as e:
+            logger.warning(f"Failed to set timestamps for {file_path}: {e}")
+    else:
+        logger.debug(f"No timestamp headers found, using current time for {file_path}")
+
+
+async def _webdav_delete(project: str, file_path: Path) -> Response:
+    """Handle WebDAV DELETE request to delete file or directory."""
+
+    try:
+        if file_path.is_dir():
+            shutil.rmtree(file_path)
+        else:
+            file_path.unlink()
+
+        logger.info(f"WebDAV: Deleted {file_path} for project {project}")
+        return Response(status_code=204)
+
+    except Exception as e:
+        logger.error(f"WebDAV: Failed to delete {file_path}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to delete: {e}") from e
+
+
+async def _webdav_mkcol(project: str, dir_path: Path) -> Response:
+    """Handle WebDAV MKCOL request to create directory."""
+
+    if dir_path.exists():
+        raise HTTPException(status_code=405, detail="Directory already exists")
+
+    try:
+        dir_path.mkdir(parents=True, exist_ok=False)
+        logger.info(f"WebDAV: Created directory {dir_path} for project {project}")
+        return Response(status_code=201)
+
+    except Exception as e:
+        logger.error(f"WebDAV: Failed to create directory {dir_path}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to create directory: {e}") from e
@@ -1,10 +1,7 @@
 """WorkOS OAuth Device Authorization for CLI."""

-import base64
-import hashlib
 import json
 import os
-import secrets
 import time
 import webbrowser

@@ -25,36 +22,12 @@ class CLIAuth:
        app_config = ConfigManager().config
        # Store tokens in data dir
        self.token_file = app_config.data_dir_path / "basic-memory-cloud.json"
-        # PKCE parameters
-        self.code_verifier = None
-        self.code_challenge = None
-
-    def generate_pkce_pair(self) -> tuple[str, str]:
-        """Generate PKCE code verifier and challenge."""
-        # Generate code verifier (43-128 characters)
-        code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode("utf-8")
-        code_verifier = code_verifier.rstrip("=")
-
-        # Generate code challenge (SHA256 hash of verifier)
-        challenge_bytes = hashlib.sha256(code_verifier.encode("utf-8")).digest()
-        code_challenge = base64.urlsafe_b64encode(challenge_bytes).decode("utf-8")
-        code_challenge = code_challenge.rstrip("=")
-
-        return code_verifier, code_challenge

    async def request_device_authorization(self) -> dict | None:
-        """Request device authorization from WorkOS with PKCE."""
+        """Request device authorization from WorkOS."""
        device_auth_url = f"{self.authkit_domain}/oauth2/device_authorization"

-        # Generate PKCE pair
-        self.code_verifier, self.code_challenge = self.generate_pkce_pair()
-
-        data = {
-            "client_id": self.client_id,
-            "scope": "openid profile email offline_access",
-            "code_challenge": self.code_challenge,
-            "code_challenge_method": "S256",
-        }
+        data = {"client_id": self.client_id, "scope": "openid profile email offline_access"}

        try:
            async with httpx.AsyncClient() as client:
@@ -77,7 +50,7 @@ class CLIAuth:
        verification_uri = device_response["verification_uri"]
        verification_uri_complete = device_response.get("verification_uri_complete")

-        console.print("\n[bold blue]Authentication Required[/bold blue]")
+        console.print("\n[bold blue]🔐 Authentication Required[/bold blue]")
        console.print("\nTo authenticate, please visit:")
        console.print(f"[bold cyan]{verification_uri}[/bold cyan]")
        console.print(f"\nAnd enter this code: [bold yellow]{user_code}[/bold yellow]")
@@ -103,7 +76,6 @@ class CLIAuth:
            "client_id": self.client_id,
            "device_code": device_code,
            "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
-            "code_verifier": self.code_verifier,
        }

        max_attempts = 60  # 5 minutes with 5-second intervals
@@ -171,7 +143,7 @@ class CLIAuth:
        # Secure the token file
        os.chmod(self.token_file, 0o600)

-        console.print(f"[green]Tokens saved to {self.token_file}[/green]")
+        console.print(f"[green]✓ Tokens saved to {self.token_file}[/green]")

    def load_tokens(self) -> dict | None:
        """Load tokens from .bm-auth.json file."""
@@ -233,7 +205,7 @@ class CLIAuth:
            if new_tokens:
                # Save new tokens (may include rotated refresh token)
                self.save_tokens(new_tokens)
-                console.print("[green]Token refreshed successfully[/green]")
+                console.print("[green]✓ Token refreshed successfully[/green]")
                return new_tokens["access_token"]
            else:
                console.print("[yellow]Token refresh failed. Please run 'login' again.[/yellow]")
@@ -244,7 +216,7 @@ class CLIAuth:

    async def login(self) -> bool:
        """Perform OAuth Device Authorization login flow."""
-        console.print("[blue]Initiating authentication...[/blue]")
+        console.print("[blue]Initiating WorkOS authentication...[/blue]")

        # Step 1: Request device authorization
        device_response = await self.request_device_authorization()
@@ -265,13 +237,13 @@ class CLIAuth:
        # Step 4: Save tokens
        self.save_tokens(tokens)

-        console.print("\n[green]Successfully authenticated with Basic Memory Cloud![/green]")
+        console.print("\n[green]✅ Successfully authenticated with WorkOS![/green]")
        return True

    def logout(self) -> None:
        """Remove stored authentication tokens."""
        if self.token_file.exists():
            self.token_file.unlink()
-            console.print("[green]Logged out successfully[/green]")
+            console.print("[green]✓ Logged out successfully[/green]")
        else:
            console.print("[yellow]No stored authentication found[/yellow]")
@@ -1,10 +1,11 @@
 """CLI commands for basic-memory."""

-from . import status, db, import_memory_json, mcp, import_claude_conversations
+from . import status, sync, db, import_memory_json, mcp, import_claude_conversations
 from . import import_claude_projects, import_chatgpt, tool, project

 __all__ = [
    "status",
+    "sync",
    "db",
    "import_memory_json",
    "mcp",
@@ -13,4 +14,5 @@ __all__ = [
    "import_chatgpt",
    "tool",
    "project",
+    "cloud",
 ]
@@ -2,5 +2,3 @@

 # Import all commands to register them with typer
 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
@@ -15,20 +15,7 @@ console = Console()
 class CloudAPIError(Exception):
    """Exception raised for cloud API errors."""

-    def __init__(
-        self, message: str, status_code: Optional[int] = None, detail: Optional[dict] = None
-    ):
-        super().__init__(message)
-        self.status_code = status_code
-        self.detail = detail or {}
-
-
-class SubscriptionRequiredError(CloudAPIError):
-    """Exception raised when user needs an active subscription."""
-
-    def __init__(self, message: str, subscribe_url: str):
-        super().__init__(message, status_code=403, detail={"error": "subscription_required"})
-        self.subscribe_url = subscribe_url
+    pass


 def get_cloud_config() -> tuple[str, str, str]:
@@ -39,10 +26,7 @@ def get_cloud_config() -> tuple[str, str, str]:


 async def get_authenticated_headers() -> dict[str, str]:
-    """
-    Get authentication headers with JWT token.
-    handles jwt refresh if needed.
-    """
+    """Get authentication headers with JWT token."""
    client_id, domain, _ = get_cloud_config()
    auth = CLIAuth(client_id=client_id, authkit_domain=domain)
    token = await auth.get_valid_token()
@@ -69,44 +53,25 @@ async def make_api_request(

    async with httpx.AsyncClient(timeout=timeout) as client:
        try:
+            console.print(f"[dim]Making {method} request to {url}[/dim]")
+            console.print(f"[dim]Headers: {dict(headers)}[/dim]")
+
            response = await client.request(method=method, url=url, headers=headers, json=json_data)
+
+            console.print(f"[dim]Response status: {response.status_code}[/dim]")
+            console.print(f"[dim]Response headers: {dict(response.headers)}[/dim]")
+
            response.raise_for_status()
            return response
        except httpx.HTTPError as e:
+            console.print(f"[red]HTTP Error details: {e}[/red]")
            # Check if this is a response error with response details
            if hasattr(e, "response") and e.response is not None:  # pyright: ignore [reportAttributeAccessIssue]
                response = e.response  # type: ignore
-
-                # Try to parse error detail from response
-                error_detail = None
+                console.print(f"[red]Response status: {response.status_code}[/red]")
+                console.print(f"[red]Response headers: {dict(response.headers)}[/red]")
                try:
-                    error_detail = response.json()
+                    console.print(f"[red]Response text: {response.text}[/red]")
                except Exception:
-                    # If JSON parsing fails, we'll handle it as a generic error
-                    pass
-
-                # Check for subscription_required error (403)
-                if response.status_code == 403 and isinstance(error_detail, dict):
-                    # Handle both FastAPI HTTPException format (nested under "detail")
-                    # and direct format
-                    detail_obj = error_detail.get("detail", error_detail)
-                    if (
-                        isinstance(detail_obj, dict)
-                        and detail_obj.get("error") == "subscription_required"
-                    ):
-                        message = detail_obj.get("message", "Active subscription required")
-                        subscribe_url = detail_obj.get(
-                            "subscribe_url", "https://basicmemory.com/subscribe"
-                        )
-                        raise SubscriptionRequiredError(
-                            message=message, subscribe_url=subscribe_url
-                        ) from e
-
-                # Raise generic CloudAPIError with status code and detail
-                raise CloudAPIError(
-                    f"API request failed: {e}",
-                    status_code=response.status_code,
-                    detail=error_detail if isinstance(error_detail, dict) else {},
-                ) from e
-
+                    console.print("[red]Could not read response text[/red]")
            raise CloudAPIError(f"API request failed: {e}") from e
@@ -1,110 +0,0 @@
-"""Cloud bisync utility functions for Basic Memory CLI."""
-
-from pathlib import Path
-
-from basic_memory.cli.commands.cloud.api_client import make_api_request
-from basic_memory.config import ConfigManager
-from basic_memory.ignore_utils import create_default_bmignore, get_bmignore_path
-from basic_memory.schemas.cloud import MountCredentials, TenantMountInfo
-
-
-class BisyncError(Exception):
-    """Exception raised for bisync-related errors."""
-
-    pass
-
-
-async def get_mount_info() -> TenantMountInfo:
-    """Get current tenant information from cloud API."""
-    try:
-        config_manager = ConfigManager()
-        config = config_manager.config
-        host_url = config.cloud_host.rstrip("/")
-
-        response = await make_api_request(method="GET", url=f"{host_url}/tenant/mount/info")
-
-        return TenantMountInfo.model_validate(response.json())
-    except Exception as e:
-        raise BisyncError(f"Failed to get tenant info: {e}") from e
-
-
-async def generate_mount_credentials(tenant_id: str) -> MountCredentials:
-    """Generate scoped credentials for syncing."""
-    try:
-        config_manager = ConfigManager()
-        config = config_manager.config
-        host_url = config.cloud_host.rstrip("/")
-
-        response = await make_api_request(method="POST", url=f"{host_url}/tenant/mount/credentials")
-
-        return MountCredentials.model_validate(response.json())
-    except Exception as e:
-        raise BisyncError(f"Failed to generate credentials: {e}") from e
-
-
-def convert_bmignore_to_rclone_filters() -> Path:
-    """Convert .bmignore patterns to rclone filter format.
-
-    Reads ~/.basic-memory/.bmignore (gitignore-style) and converts to
-    ~/.basic-memory/.bmignore.rclone (rclone filter format).
-
-    Only regenerates if .bmignore has been modified since last conversion.
-
-    Returns:
-        Path to converted rclone filter file
-    """
-    # Ensure .bmignore exists
-    create_default_bmignore()
-
-    bmignore_path = get_bmignore_path()
-    # Create rclone filter path: ~/.basic-memory/.bmignore -> ~/.basic-memory/.bmignore.rclone
-    rclone_filter_path = bmignore_path.parent / f"{bmignore_path.name}.rclone"
-
-    # Skip regeneration if rclone file is newer than bmignore
-    if rclone_filter_path.exists():
-        bmignore_mtime = bmignore_path.stat().st_mtime
-        rclone_mtime = rclone_filter_path.stat().st_mtime
-        if rclone_mtime >= bmignore_mtime:
-            return rclone_filter_path
-
-    # Read .bmignore patterns
-    patterns = []
-    try:
-        with bmignore_path.open("r", encoding="utf-8") as f:
-            for line in f:
-                line = line.strip()
-                # Keep comments and empty lines
-                if not line or line.startswith("#"):
-                    patterns.append(line)
-                    continue
-
-                # Convert gitignore pattern to rclone filter syntax
-                # gitignore: node_modules  → rclone: - node_modules/**
-                # gitignore: *.pyc        → rclone: - *.pyc
-                if "*" in line:
-                    # Pattern already has wildcard, just add exclude prefix
-                    patterns.append(f"- {line}")
-                else:
-                    # Directory pattern - add /** for recursive exclude
-                    patterns.append(f"- {line}/**")
-
-    except Exception:
-        # If we can't read the file, create a minimal filter
-        patterns = ["# Error reading .bmignore, using minimal filters", "- .git/**"]
-
-    # Write rclone filter file
-    rclone_filter_path.write_text("\n".join(patterns) + "\n")
-
-    return rclone_filter_path
-
-
-def get_bisync_filter_path() -> Path:
-    """Get path to bisync filter file.
-
-    Uses ~/.basic-memory/.bmignore (converted to rclone format).
-    The file is automatically created with default patterns on first use.
-
-    Returns:
-        Path to rclone filter file
-    """
-    return convert_bmignore_to_rclone_filters()
@@ -1,101 +0,0 @@
-"""Shared utilities for cloud operations."""
-
-from basic_memory.cli.commands.cloud.api_client import make_api_request
-from basic_memory.config import ConfigManager
-from basic_memory.schemas.cloud import (
-    CloudProjectList,
-    CloudProjectCreateRequest,
-    CloudProjectCreateResponse,
-)
-from basic_memory.utils import generate_permalink
-
-
-class CloudUtilsError(Exception):
-    """Exception raised for cloud utility errors."""
-
-    pass
-
-
-async def fetch_cloud_projects() -> CloudProjectList:
-    """Fetch list of projects from cloud API.
-
-    Returns:
-        CloudProjectList with projects from cloud
-    """
-    try:
-        config_manager = ConfigManager()
-        config = config_manager.config
-        host_url = config.cloud_host.rstrip("/")
-
-        response = await make_api_request(method="GET", url=f"{host_url}/proxy/projects/projects")
-
-        return CloudProjectList.model_validate(response.json())
-    except Exception as e:
-        raise CloudUtilsError(f"Failed to fetch cloud projects: {e}") from e
-
-
-async def create_cloud_project(project_name: str) -> CloudProjectCreateResponse:
-    """Create a new project on cloud.
-
-    Args:
-        project_name: Name of project to create
-
-    Returns:
-        CloudProjectCreateResponse with project details from API
-    """
-    try:
-        config_manager = ConfigManager()
-        config = config_manager.config
-        host_url = config.cloud_host.rstrip("/")
-
-        # Use generate_permalink to ensure consistent naming
-        project_path = generate_permalink(project_name)
-
-        project_data = CloudProjectCreateRequest(
-            name=project_name,
-            path=project_path,
-            set_default=False,
-        )
-
-        response = await make_api_request(
-            method="POST",
-            url=f"{host_url}/proxy/projects/projects",
-            headers={"Content-Type": "application/json"},
-            json_data=project_data.model_dump(),
-        )
-
-        return CloudProjectCreateResponse.model_validate(response.json())
-    except Exception as e:
-        raise CloudUtilsError(f"Failed to create cloud project '{project_name}': {e}") from e
-
-
-async def sync_project(project_name: str, force_full: bool = False) -> None:
-    """Trigger sync for a specific project on cloud.
-
-    Args:
-        project_name: Name of project to sync
-        force_full: If True, force a full scan bypassing watermark optimization
-    """
-    try:
-        from basic_memory.cli.commands.command_utils import run_sync
-
-        await run_sync(project=project_name, force_full=force_full)
-    except Exception as e:
-        raise CloudUtilsError(f"Failed to sync project '{project_name}': {e}") from e
-
-
-async def project_exists(project_name: str) -> bool:
-    """Check if a project exists on cloud.
-
-    Args:
-        project_name: Name of project to check
-
-    Returns:
-        True if project exists, False otherwise
-    """
-    try:
-        projects = await fetch_cloud_projects()
-        project_names = {p.name for p in projects.projects}
-        return project_name in project_names
-    except Exception:
-        return False
@@ -1,103 +1,325 @@
 """Core cloud commands for Basic Memory CLI."""

 import asyncio
+from pathlib import Path
+from typing import Optional

+import httpx
 import typer
 from rich.console import Console
+from rich.table import Table

 from basic_memory.cli.app import cloud_app
 from basic_memory.cli.auth import CLIAuth
-from basic_memory.config import ConfigManager
 from basic_memory.cli.commands.cloud.api_client import (
    CloudAPIError,
-    SubscriptionRequiredError,
    get_cloud_config,
    make_api_request,
+    get_authenticated_headers,
 )
-from basic_memory.cli.commands.cloud.bisync_commands import (
-    BisyncError,
-    generate_mount_credentials,
-    get_mount_info,
-)
-from basic_memory.cli.commands.cloud.rclone_config import configure_rclone_remote
-from basic_memory.cli.commands.cloud.rclone_installer import (
-    RcloneInstallError,
-    install_rclone,
+from basic_memory.cli.commands.cloud.mount_commands import (
+    mount_cloud_files,
+    setup_cloud_mount,
+    show_mount_status,
+    unmount_cloud_files,
 )
+from basic_memory.cli.commands.cloud.rclone_config import MOUNT_PROFILES
+from basic_memory.ignore_utils import load_gitignore_patterns, should_ignore_path
+from basic_memory.utils import generate_permalink

 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():
-        client_id, domain, host_url = get_cloud_config()
+        client_id, domain, _ = get_cloud_config()
        auth = CLIAuth(client_id=client_id, authkit_domain=domain)

-        try:
-            success = await auth.login()
-            if not success:
-                console.print("[red]Login failed[/red]")
-                raise typer.Exit(1)
-
-            # Test subscription access by calling a protected endpoint
-            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]")
-
-        except SubscriptionRequiredError as e:
-            console.print("\n[red]Subscription Required[/red]\n")
-            console.print(f"[yellow]{e.args[0]}[/yellow]\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]"
-            )
+        success = await auth.login()
+        if not success:
+            console.print("[red]Login failed[/red]")
            raise typer.Exit(1)

    asyncio.run(_login())


-@cloud_app.command()
-def logout():
-    """Disable cloud mode and return to local mode."""
+# Project commands

-    # Disable cloud mode
-    config_manager = ConfigManager()
-    config = config_manager.load_config()
-    config.cloud_mode = False
-    config_manager.save_config(config)
+project_app = typer.Typer(help="Manage Basic Memory Cloud Projects")
+cloud_app.add_typer(project_app, name="project")

-    console.print("[green]Cloud mode disabled[/green]")
-    console.print("[dim]All CLI commands now work locally[/dim]")
+
+@project_app.command("list")
+def list_projects() -> None:
+    """List projects on the cloud instance."""
+
+    try:
+        # Get cloud configuration
+        _, _, host_url = get_cloud_config()
+        host_url = host_url.rstrip("/")
+
+        console.print(f"[blue]Fetching projects from {host_url}...[/blue]")
+
+        # Make API request to list projects
+        response = asyncio.run(
+            make_api_request(method="GET", url=f"{host_url}/proxy/projects/projects")
+        )
+
+        projects_data = response.json()
+
+        if not projects_data.get("projects"):
+            console.print("[yellow]No projects found on the cloud instance.[/yellow]")
+            return
+
+        # Create table for display
+        table = Table(
+            title="Cloud Projects", show_header=True, header_style="bold blue", min_width=60
+        )
+        table.add_column("Name", style="green", min_width=20)
+        table.add_column("Path", style="dim", min_width=30)
+
+        for project in projects_data["projects"]:
+            # Format the path for display
+            path = project.get("path", "")
+            if path.startswith("/"):
+                path = f"~{path}" if path.startswith(str(Path.home())) else path
+
+            table.add_row(
+                project.get("name", "unnamed"),
+                path,
+            )
+
+        console.print(table)
+        console.print(f"\n[green]Found {len(projects_data['projects'])} project(s)[/green]")
+
+    except CloudAPIError as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@project_app.command("add")
+def add_project(
+    name: str = typer.Argument(..., help="Name of the project to add"),
+    set_default: bool = typer.Option(False, "--default", "-d", help="Set as default project"),
+) -> None:
+    """Create a new project on the cloud instance."""
+
+    # Get cloud configuration
+    _, _, host_url = get_cloud_config()
+    host_url = host_url.rstrip("/")
+
+    # Prepare headers
+    headers = {"Content-Type": "application/json"}
+
+    project_path = generate_permalink(name)
+    # Prepare project data
+    project_data = {
+        "name": name,
+        "path": project_path,
+        "set_default": set_default,
+    }
+
+    console.print(project_data)
+
+    try:
+        console.print(f"[blue]Creating project '{name}' on {host_url}...[/blue]")
+
+        # Make API request to create project
+        response = asyncio.run(
+            make_api_request(
+                method="POST",
+                url=f"{host_url}/proxy/projects/projects",
+                headers=headers,
+                json_data=project_data,
+            )
+        )
+
+        result = response.json()
+
+        console.print(f"[green]Project '{name}' created successfully![/green]")
+
+        # Display project details
+        if "project" in result:
+            project = result["project"]
+            console.print(f"  Name: {project.get('name', name)}")
+            console.print(f"  Path: {project.get('path', 'unknown')}")
+            if project.get("id"):
+                console.print(f"  ID: {project['id']}")
+
+    except CloudAPIError as e:
+        console.print(f"[red]Error creating project: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("upload")
+def upload_files(
+    project: str = typer.Argument(..., help="Project name to upload to"),
+    path_to_files: str = typer.Argument(..., help="Local path to files or directory to upload"),
+    preserve_timestamps: bool = typer.Option(
+        True,
+        "--preserve-timestamps/--no-preserve-timestamps",
+        help="Preserve file modification times",
+    ),
+    respect_gitignore: bool = typer.Option(
+        True,
+        "--respect-gitignore/--no-gitignore",
+        help="Respect .gitignore patterns and skip common development artifacts",
+    ),
+) -> None:
+    """Upload files to a cloud project using WebDAV."""
+
+    # Get cloud configuration
+    _, _, host_url = get_cloud_config()
+    host_url = host_url.rstrip("/")
+
+    # Validate local path
+    local_path = Path(path_to_files).expanduser().resolve()
+    if not local_path.exists():
+        console.print(f"[red]Error: Path '{path_to_files}' does not exist[/red]")
+        raise typer.Exit(1)
+
+    # Prepare headers
+    headers = {}
+
+    try:
+        # Load gitignore patterns (only if enabled)
+        ignore_patterns = load_gitignore_patterns(local_path) if respect_gitignore else set()
+
+        # Collect files to upload
+        files_to_upload = []
+        ignored_count = 0
+
+        if local_path.is_file():
+            # Single file upload - check if it should be ignored
+            if not respect_gitignore or not should_ignore_path(
+                local_path, local_path.parent, ignore_patterns
+            ):
+                files_to_upload.append(local_path)
+            else:
+                ignored_count += 1
+        else:
+            # Recursively collect all files
+            for file_path in local_path.rglob("*"):
+                if file_path.is_file():
+                    if not respect_gitignore or not should_ignore_path(
+                        file_path, local_path, ignore_patterns
+                    ):
+                        files_to_upload.append(file_path)
+                    else:
+                        ignored_count += 1
+
+        # Show summary
+        if ignored_count > 0 and respect_gitignore:
+            console.print(
+                f"[dim]Ignored {ignored_count} file(s) based on .gitignore and default patterns[/dim]"
+            )
+
+        if not files_to_upload:
+            console.print("[yellow]No files found to upload[/yellow]")
+            return
+
+        console.print(
+            f"[blue]Uploading {len(files_to_upload)} file(s) to project '{project}' on {host_url}...[/blue]"
+        )
+
+        # Upload files using WebDAV
+        asyncio.run(
+            _upload_files_webdav(
+                files_to_upload=files_to_upload,
+                local_base_path=local_path,
+                project=project,
+                host_url=host_url,
+                headers=headers,
+                preserve_timestamps=preserve_timestamps,
+            )
+        )
+
+        console.print(f"[green]Successfully uploaded {len(files_to_upload)} file(s)![/green]")
+
+    except CloudAPIError as e:
+        console.print(f"[red]Error uploading files: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+async def _upload_files_webdav(
+    files_to_upload: list[Path],
+    local_base_path: Path,
+    project: str,
+    host_url: str,
+    headers: dict,
+    preserve_timestamps: bool,
+) -> None:
+    """Upload files using WebDAV protocol."""
+
+    # Get authentication headers for WebDAV uploads
+    auth_headers = await get_authenticated_headers()
+
+    async with httpx.AsyncClient(timeout=300.0) as client:
+        for file_path in files_to_upload:
+            # Calculate relative path for WebDAV outside try block
+            if local_base_path.is_file():
+                # Single file upload - use just the filename
+                relative_path = file_path.name
+            else:
+                # Directory upload - preserve structure
+                relative_path = file_path.relative_to(local_base_path)
+
+            try:
+                # WebDAV URL
+                webdav_url = f"{host_url}/proxy/{project}/webdav/{relative_path}"
+
+                # Prepare upload headers
+                upload_headers = dict(headers)
+                upload_headers.update(auth_headers)
+
+                # Add timestamp preservation header if requested
+                if preserve_timestamps:
+                    mtime = file_path.stat().st_mtime
+                    upload_headers["X-OC-Mtime"] = str(mtime)
+
+                # Disable compression for WebDAV as well
+                upload_headers.setdefault("Accept-Encoding", "identity")
+
+                # Read file content
+                file_content = file_path.read_bytes()
+
+                # console.print(f"[dim]Uploading {relative_path} to {webdav_url}[/dim]")
+
+                # Upload file
+                response = await client.put(
+                    webdav_url, content=file_content, headers=upload_headers
+                )
+
+                # console.print(f"[dim]WebDAV response status: {response.status_code}[/dim]")
+                response.raise_for_status()
+
+                # Show file upload progress
+                console.print(f"  ✓ {relative_path}")
+
+            except httpx.HTTPError as e:
+                console.print(f"  ✗ {relative_path} - {e}")
+                if hasattr(e, "response") and e.response is not None:  # pyright: ignore [reportAttributeAccessIssue]
+                    response = e.response  # type: ignore
+                    console.print(f"[red]WebDAV Response status: {response.status_code}[/red]")
+                    console.print(f"[red]WebDAV Response headers: {dict(response.headers)}[/red]")
+                raise CloudAPIError(f"Failed to upload {file_path.name}: {e}") from e


@cloud_app.command("status")
 def status() -> None:
-    """Check cloud mode status and cloud instance health."""
-    # Check cloud mode
-    config_manager = ConfigManager()
-    config = config_manager.load_config()
-
-    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]")
-        return
+    """Check the status of the cloud instance."""

    # Get cloud configuration
    _, _, host_url = get_cloud_config()
@@ -107,7 +329,7 @@ def status() -> None:
    headers = {}

    try:
-        console.print("\n[blue]Checking cloud instance health...[/blue]")
+        console.print(f"[blue]Checking status of {host_url}...[/blue]")

        # Make API request to check health
        response = asyncio.run(
@@ -126,70 +348,51 @@ def status() -> None:
        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]")
+        console.print(f"[red]Error checking status: {e}[/red]")
        raise typer.Exit(1)
    except Exception as e:
        console.print(f"[red]Unexpected error: {e}[/red]")
        raise typer.Exit(1)


+# Mount commands
+
+
@cloud_app.command("setup")
 def setup() -> None:
-    """Set up cloud sync by installing rclone and configuring credentials.
+    """Set up local file access with automatic rclone installation and configuration."""
+    setup_cloud_mount()

-    SPEC-20: Simplified to project-scoped workflow.
-    After setup, use project commands for syncing:
-      bm project add <name> <path> --local-path ~/projects/<name>
-      bm project bisync --name <name> --resync  # First time
-      bm project bisync --name <name>            # Subsequent syncs
-    """
-    console.print("[bold blue]Basic Memory Cloud Setup[/bold blue]")
-    console.print("Setting up cloud sync with rclone...\n")

+@cloud_app.command("mount")
+def mount(
+    profile: str = typer.Option(
+        "balanced", help=f"Mount profile: {', '.join(MOUNT_PROFILES.keys())}"
+    ),
+    path: Optional[str] = typer.Option(
+        None, help="Custom mount path (default: ~/basic-memory-{tenant-id})"
+    ),
+) -> None:
+    """Mount cloud files locally for editing."""
    try:
-        # Step 1: Install rclone
-        console.print("[blue]Step 1: Installing rclone...[/blue]")
-        install_rclone()
-
-        # Step 2: Get tenant info
-        console.print("\n[blue]Step 2: Getting tenant information...[/blue]")
-        tenant_info = asyncio.run(get_mount_info())
-        console.print(f"[green]Found tenant: {tenant_info.tenant_id}[/green]")
-
-        # Step 3: Generate credentials
-        console.print("\n[blue]Step 3: Generating sync credentials...[/blue]")
-        creds = asyncio.run(generate_mount_credentials(tenant_info.tenant_id))
-        console.print("[green]Generated secure credentials[/green]")
-
-        # Step 4: Configure rclone remote
-        console.print("\n[blue]Step 4: Configuring rclone remote...[/blue]")
-        configure_rclone_remote(
-            access_key=creds.access_key,
-            secret_key=creds.secret_key,
-        )
-
-        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("\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):")
-        console.print("   bm project bisync --name research --resync --dry-run")
-        console.print("\n3. If all looks good, run the actual sync:")
-        console.print("   bm project bisync --name research --resync")
-        console.print("\n4. Subsequent syncs (no --resync needed):")
-        console.print("   bm project bisync --name research")
-        console.print(
-            "\n[dim]Tip: Always use --dry-run first to preview changes before syncing[/dim]"
-        )
-
-    except (RcloneInstallError, BisyncError, CloudAPIError) as e:
-        console.print(f"\n[red]Setup failed: {e}[/red]")
-        raise typer.Exit(1)
+        mount_cloud_files(profile_name=profile)
    except Exception as e:
-        console.print(f"\n[red]Unexpected error during setup: {e}[/red]")
+        console.print(f"[red]Mount failed: {e}[/red]")
        raise typer.Exit(1)
+
+
+@cloud_app.command("unmount")
+def unmount() -> None:
+    """Unmount cloud files."""
+    try:
+        unmount_cloud_files()
+    except Exception as e:
+        console.print(f"[red]Unmount failed: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("mount-status")
+def mount_status() -> None:
+    """Show current mount status."""
+    show_mount_status()
@@ -0,0 +1,295 @@
+"""Cloud mount commands for Basic Memory CLI."""
+
+import asyncio
+import subprocess
+import time
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from basic_memory.cli.commands.cloud.api_client import CloudAPIError, make_api_request
+from basic_memory.cli.commands.cloud.rclone_config import (
+    MOUNT_PROFILES,
+    add_tenant_to_rclone_config,
+    build_mount_command,
+    cleanup_orphaned_rclone_processes,
+    get_default_mount_path,
+    get_rclone_processes,
+    is_path_mounted,
+    unmount_path,
+)
+from basic_memory.cli.commands.cloud.rclone_installer import RcloneInstallError, install_rclone
+from basic_memory.config import ConfigManager
+
+console = Console()
+
+
+class MountError(Exception):
+    """Exception raised for mount-related errors."""
+
+    pass
+
+
+async def get_tenant_info() -> dict:
+    """Get current tenant information from cloud API."""
+    try:
+        config_manager = ConfigManager()
+        config = config_manager.config
+        host_url = config.cloud_host.rstrip("/")
+
+        response = await make_api_request(method="GET", url=f"{host_url}/tenant/mount/info")
+
+        return response.json()
+    except Exception as e:
+        raise MountError(f"Failed to get tenant info: {e}") from e
+
+
+async def generate_mount_credentials(tenant_id: str) -> dict:
+    """Generate scoped credentials for mounting."""
+    try:
+        config_manager = ConfigManager()
+        config = config_manager.config
+        host_url = config.cloud_host.rstrip("/")
+
+        response = await make_api_request(method="POST", url=f"{host_url}/tenant/mount/credentials")
+
+        return response.json()
+    except Exception as e:
+        raise MountError(f"Failed to generate mount credentials: {e}") from e
+
+
+def setup_cloud_mount() -> None:
+    """Set up cloud mount with rclone installation and configuration."""
+    console.print("[bold blue]Basic Memory Cloud Setup[/bold blue]")
+    console.print("Setting up local file access to your cloud tenant...\n")
+
+    try:
+        # Step 1: Install rclone
+        console.print("[blue]Step 1: Installing rclone...[/blue]")
+        install_rclone()
+
+        # Step 2: Get tenant info
+        console.print("\n[blue]Step 2: Getting tenant information...[/blue]")
+        tenant_info = asyncio.run(get_tenant_info())
+
+        tenant_id = tenant_info.get("tenant_id")
+        bucket_name = tenant_info.get("bucket_name")
+
+        if not tenant_id or not bucket_name:
+            raise MountError("Invalid tenant information received from cloud API")
+
+        console.print(f"[green]✓ Found tenant: {tenant_id}[/green]")
+        console.print(f"[green]✓ Bucket: {bucket_name}[/green]")
+
+        # Step 3: Generate mount credentials
+        console.print("\n[blue]Step 3: Generating mount credentials...[/blue]")
+        creds = asyncio.run(generate_mount_credentials(tenant_id))
+
+        access_key = creds.get("access_key")
+        secret_key = creds.get("secret_key")
+
+        if not access_key or not secret_key:
+            raise MountError("Failed to generate mount credentials")
+
+        console.print("[green]✓ Generated secure credentials[/green]")
+
+        # Step 4: Configure rclone
+        console.print("\n[blue]Step 4: Configuring rclone...[/blue]")
+        add_tenant_to_rclone_config(
+            tenant_id=tenant_id,
+            bucket_name=bucket_name,
+            access_key=access_key,
+            secret_key=secret_key,
+        )
+
+        # Step 5: Perform initial mount
+        console.print("\n[blue]Step 5: Mounting cloud files...[/blue]")
+        mount_path = get_default_mount_path(tenant_id)
+        MOUNT_PROFILES["balanced"]
+
+        mount_cloud_files(
+            tenant_id=tenant_id,
+            bucket_name=bucket_name,
+            mount_path=mount_path,
+            profile_name="balanced",
+        )
+
+        console.print("\n[bold green]✓ Cloud setup completed successfully![/bold green]")
+        console.print("\nYour cloud files are now accessible at:")
+        console.print(f"  {mount_path}")
+        console.print("\nYou can now edit files locally and they will sync to the cloud!")
+        console.print("\nUseful commands:")
+        console.print("  basic-memory cloud mount-status    # Check mount status")
+        console.print("  basic-memory cloud unmount         # Unmount files")
+        console.print("  basic-memory cloud mount --profile fast  # Remount with faster sync")
+
+    except (RcloneInstallError, MountError, CloudAPIError) as e:
+        console.print(f"\n[red]Setup failed: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"\n[red]Unexpected error during setup: {e}[/red]")
+        raise typer.Exit(1)
+
+
+def mount_cloud_files(
+    tenant_id: Optional[str] = None,
+    bucket_name: Optional[str] = None,
+    mount_path: Optional[Path] = None,
+    profile_name: str = "balanced",
+) -> None:
+    """Mount cloud files with specified profile."""
+
+    try:
+        # Get tenant info if not provided
+        if not tenant_id or not bucket_name:
+            tenant_info = asyncio.run(get_tenant_info())
+            tenant_id = tenant_info.get("tenant_id")
+            bucket_name = tenant_info.get("bucket_name")
+
+            if not tenant_id or not bucket_name:
+                raise MountError("Could not determine tenant information")
+
+        # Set default mount path if not provided
+        if not mount_path:
+            mount_path = get_default_mount_path(tenant_id)
+
+        # Get mount profile
+        if profile_name not in MOUNT_PROFILES:
+            raise MountError(
+                f"Unknown profile: {profile_name}. Available: {list(MOUNT_PROFILES.keys())}"
+            )
+
+        profile = MOUNT_PROFILES[profile_name]
+
+        # Check if already mounted
+        if is_path_mounted(mount_path):
+            console.print(f"[yellow]Path {mount_path} is already mounted[/yellow]")
+            console.print("Use 'basic-memory cloud unmount' first, or mount to a different path")
+            return
+
+        # Create mount directory
+        mount_path.mkdir(parents=True, exist_ok=True)
+
+        # Build and execute mount command
+        mount_cmd = build_mount_command(tenant_id, bucket_name, mount_path, profile)
+
+        console.print(
+            f"[blue]Mounting with profile '{profile_name}' ({profile.description})...[/blue]"
+        )
+        console.print(f"[dim]Command: {' '.join(mount_cmd)}[/dim]")
+
+        result = subprocess.run(mount_cmd, capture_output=True, text=True)
+
+        if result.returncode != 0:
+            error_msg = result.stderr or "Unknown error"
+            raise MountError(f"Mount command failed: {error_msg}")
+
+        # Wait a moment for mount to establish
+        time.sleep(2)
+
+        # Verify mount
+        if is_path_mounted(mount_path):
+            console.print(f"[green]✓ Successfully mounted to {mount_path}[/green]")
+            console.print(f"[green]✓ Sync profile: {profile.description}[/green]")
+        else:
+            raise MountError("Mount command succeeded but path is not mounted")
+
+    except MountError:
+        raise
+    except Exception as e:
+        raise MountError(f"Unexpected error during mount: {e}") from e
+
+
+def unmount_cloud_files(tenant_id: Optional[str] = None) -> None:
+    """Unmount cloud files."""
+
+    try:
+        # Get tenant info if not provided
+        if not tenant_id:
+            tenant_info = asyncio.run(get_tenant_info())
+            tenant_id = tenant_info.get("tenant_id")
+
+            if not tenant_id:
+                raise MountError("Could not determine tenant ID")
+
+        mount_path = get_default_mount_path(tenant_id)
+
+        if not is_path_mounted(mount_path):
+            console.print(f"[yellow]Path {mount_path} is not mounted[/yellow]")
+            return
+
+        console.print(f"[blue]Unmounting {mount_path}...[/blue]")
+
+        # Unmount the path
+        if unmount_path(mount_path):
+            console.print(f"[green]✓ Successfully unmounted {mount_path}[/green]")
+
+            # Clean up any orphaned rclone processes
+            killed_count = cleanup_orphaned_rclone_processes()
+            if killed_count > 0:
+                console.print(
+                    f"[green]✓ Cleaned up {killed_count} orphaned rclone process(es)[/green]"
+                )
+        else:
+            console.print(f"[red]✗ Failed to unmount {mount_path}[/red]")
+            console.print("You may need to manually unmount or restart your system")
+
+    except MountError:
+        raise
+    except Exception as e:
+        raise MountError(f"Unexpected error during unmount: {e}") from e
+
+
+def show_mount_status() -> None:
+    """Show current mount status and running processes."""
+
+    try:
+        # Get tenant info
+        tenant_info = asyncio.run(get_tenant_info())
+        tenant_id = tenant_info.get("tenant_id")
+
+        if not tenant_id:
+            console.print("[red]Could not determine tenant ID[/red]")
+            return
+
+        mount_path = get_default_mount_path(tenant_id)
+
+        # Create status table
+        table = Table(title="Cloud Mount Status", show_header=True, header_style="bold blue")
+        table.add_column("Property", style="green", min_width=15)
+        table.add_column("Value", style="dim", min_width=30)
+
+        # Check mount status
+        is_mounted = is_path_mounted(mount_path)
+        mount_status = "[green]✓ Mounted[/green]" if is_mounted else "[red]✗ Not mounted[/red]"
+
+        table.add_row("Tenant ID", tenant_id)
+        table.add_row("Mount Path", str(mount_path))
+        table.add_row("Status", mount_status)
+
+        # Get rclone processes
+        processes = get_rclone_processes()
+        if processes:
+            table.add_row("rclone Processes", f"{len(processes)} running")
+        else:
+            table.add_row("rclone Processes", "None")
+
+        console.print(table)
+
+        # Show running processes details
+        if processes:
+            console.print("\n[bold]Running rclone processes:[/bold]")
+            for proc in processes:
+                console.print(f"  PID {proc['pid']}: {proc['command'][:80]}...")
+
+        # Show mount profiles
+        console.print("\n[bold]Available mount profiles:[/bold]")
+        for name, profile in MOUNT_PROFILES.items():
+            console.print(f"  {name}: {profile.description}")
+
+    except Exception as e:
+        console.print(f"[red]Error getting mount status: {e}[/red]")
+        raise typer.Exit(1)
@@ -1,326 +0,0 @@
-"""Project-scoped rclone sync commands for Basic Memory Cloud.
-
-This module provides simplified, project-scoped rclone operations:
- Each project syncs independently
- Uses single "basic-memory-cloud" remote (not tenant-specific)
- Balanced defaults from SPEC-8 Phase 4 testing
- Per-project bisync state tracking
-
-Replaces tenant-wide sync with project-scoped workflows.
-"""
-
-import subprocess
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Optional
-
-from rich.console import Console
-
-from basic_memory.cli.commands.cloud.rclone_installer import is_rclone_installed
-from basic_memory.utils import normalize_project_path
-
-console = Console()
-
-
-class RcloneError(Exception):
-    """Exception raised for rclone command errors."""
-
-    pass
-
-
-def check_rclone_installed() -> None:
-    """Check if rclone is installed and raise helpful error if not.
-
-    Raises:
-        RcloneError: If rclone is not installed with installation instructions
-    """
-    if not is_rclone_installed():
-        raise RcloneError(
-            "rclone is not installed.\n\n"
-            "Install rclone by running: bm cloud setup\n"
-            "Or install manually from: https://rclone.org/downloads/\n\n"
-            "Windows users: Ensure you have a package manager installed (winget, chocolatey, or scoop)"
-        )
-
-
-@dataclass
-class SyncProject:
-    """Project configured for cloud sync.
-
-    Attributes:
-        name: Project name
-        path: Cloud path (e.g., "app/data/research")
-        local_sync_path: Local directory for syncing (optional)
-    """
-
-    name: str
-    path: str
-    local_sync_path: Optional[str] = None
-
-
-def get_bmignore_filter_path() -> Path:
-    """Get path to rclone filter file.
-
-    Uses ~/.basic-memory/.bmignore converted to rclone format.
-    File is automatically created with default patterns on first use.
-
-    Returns:
-        Path to rclone filter file
-    """
-    # Import here to avoid circular dependency
-    from basic_memory.cli.commands.cloud.bisync_commands import (
-        convert_bmignore_to_rclone_filters,
-    )
-
-    return convert_bmignore_to_rclone_filters()
-
-
-def get_project_bisync_state(project_name: str) -> Path:
-    """Get path to project's bisync state directory.
-
-    Args:
-        project_name: Name of the project
-
-    Returns:
-        Path to bisync state directory for this project
-    """
-    return Path.home() / ".basic-memory" / "bisync-state" / project_name
-
-
-def bisync_initialized(project_name: str) -> bool:
-    """Check if bisync has been initialized for this project.
-
-    Args:
-        project_name: Name of the project
-
-    Returns:
-        True if bisync state exists, False otherwise
-    """
-    state_path = get_project_bisync_state(project_name)
-    return state_path.exists() and any(state_path.iterdir())
-
-
-def get_project_remote(project: SyncProject, bucket_name: str) -> str:
-    """Build rclone remote path for project.
-
-    Args:
-        project: Project with cloud path
-        bucket_name: S3 bucket name
-
-    Returns:
-        Remote path like "basic-memory-cloud:bucket-name/basic-memory-llc"
-
-    Note:
-        The API returns paths like "/app/data/basic-memory-llc" because the S3 bucket
-        is mounted at /app/data on the fly machine. We need to strip the /app/data/
-        prefix to get the actual S3 path within the bucket.
-    """
-    # Normalize path to strip /app/data/ mount point prefix
-    cloud_path = normalize_project_path(project.path).lstrip("/")
-    return f"basic-memory-cloud:{bucket_name}/{cloud_path}"
-
-
-def project_sync(
-    project: SyncProject,
-    bucket_name: str,
-    dry_run: bool = False,
-    verbose: bool = False,
-) -> bool:
-    """One-way sync: local → cloud.
-
-    Makes cloud identical to local using rclone sync.
-
-    Args:
-        project: Project to sync
-        bucket_name: S3 bucket name
-        dry_run: Preview changes without applying
-        verbose: Show detailed output
-
-    Returns:
-        True if sync succeeded, False otherwise
-
-    Raises:
-        RcloneError: If project has no local_sync_path configured or rclone not installed
-    """
-    check_rclone_installed()
-
-    if not project.local_sync_path:
-        raise RcloneError(f"Project {project.name} has no local_sync_path configured")
-
-    local_path = Path(project.local_sync_path).expanduser()
-    remote_path = get_project_remote(project, bucket_name)
-    filter_path = get_bmignore_filter_path()
-
-    cmd = [
-        "rclone",
-        "sync",
-        str(local_path),
-        remote_path,
-        "--filter-from",
-        str(filter_path),
-    ]
-
-    if verbose:
-        cmd.append("--verbose")
-    else:
-        cmd.append("--progress")
-
-    if dry_run:
-        cmd.append("--dry-run")
-
-    result = subprocess.run(cmd, text=True)
-    return result.returncode == 0
-
-
-def project_bisync(
-    project: SyncProject,
-    bucket_name: str,
-    dry_run: bool = False,
-    resync: bool = False,
-    verbose: bool = False,
-) -> bool:
-    """Two-way sync: local ↔ cloud.
-
-    Uses rclone bisync with balanced defaults:
-    - conflict_resolve: newer (auto-resolve to most recent)
-    - max_delete: 25 (safety limit)
-    - compare: modtime (ignore size differences from line ending conversions)
-    - check_access: false (skip for performance)
-
-    Args:
-        project: Project to sync
-        bucket_name: S3 bucket name
-        dry_run: Preview changes without applying
-        resync: Force resync to establish new baseline
-        verbose: Show detailed output
-
-    Returns:
-        True if bisync succeeded, False otherwise
-
-    Raises:
-        RcloneError: If project has no local_sync_path, needs --resync, or rclone not installed
-    """
-    check_rclone_installed()
-
-    if not project.local_sync_path:
-        raise RcloneError(f"Project {project.name} has no local_sync_path configured")
-
-    local_path = Path(project.local_sync_path).expanduser()
-    remote_path = get_project_remote(project, bucket_name)
-    filter_path = get_bmignore_filter_path()
-    state_path = get_project_bisync_state(project.name)
-
-    # Ensure state directory exists
-    state_path.mkdir(parents=True, exist_ok=True)
-
-    cmd = [
-        "rclone",
-        "bisync",
-        str(local_path),
-        remote_path,
-        "--create-empty-src-dirs",
-        "--resilient",
-        "--conflict-resolve=newer",
-        "--max-delete=25",
-        "--compare=modtime",  # Ignore size differences from line ending conversions
-        "--filter-from",
-        str(filter_path),
-        "--workdir",
-        str(state_path),
-    ]
-
-    if verbose:
-        cmd.append("--verbose")
-    else:
-        cmd.append("--progress")
-
-    if dry_run:
-        cmd.append("--dry-run")
-
-    if resync:
-        cmd.append("--resync")
-
-    # Check if first run requires resync
-    if not resync and not bisync_initialized(project.name) and not dry_run:
-        raise RcloneError(
-            f"First bisync for {project.name} requires --resync to establish baseline.\n"
-            f"Run: bm project bisync --name {project.name} --resync"
-        )
-
-    result = subprocess.run(cmd, text=True)
-    return result.returncode == 0
-
-
-def project_check(
-    project: SyncProject,
-    bucket_name: str,
-    one_way: bool = False,
-) -> bool:
-    """Check integrity between local and cloud.
-
-    Verifies files match without transferring data.
-
-    Args:
-        project: Project to check
-        bucket_name: S3 bucket name
-        one_way: Only check for missing files on destination (faster)
-
-    Returns:
-        True if files match, False if differences found
-
-    Raises:
-        RcloneError: If project has no local_sync_path configured or rclone not installed
-    """
-    check_rclone_installed()
-
-    if not project.local_sync_path:
-        raise RcloneError(f"Project {project.name} has no local_sync_path configured")
-
-    local_path = Path(project.local_sync_path).expanduser()
-    remote_path = get_project_remote(project, bucket_name)
-    filter_path = get_bmignore_filter_path()
-
-    cmd = [
-        "rclone",
-        "check",
-        str(local_path),
-        remote_path,
-        "--filter-from",
-        str(filter_path),
-    ]
-
-    if one_way:
-        cmd.append("--one-way")
-
-    result = subprocess.run(cmd, capture_output=True, text=True)
-    return result.returncode == 0
-
-
-def project_ls(
-    project: SyncProject,
-    bucket_name: str,
-    path: Optional[str] = None,
-) -> list[str]:
-    """List files in remote project.
-
-    Args:
-        project: Project to list files from
-        bucket_name: S3 bucket name
-        path: Optional subdirectory within project
-
-    Returns:
-        List of file paths
-
-    Raises:
-        subprocess.CalledProcessError: If rclone command fails
-        RcloneError: If rclone is not installed
-    """
-    check_rclone_installed()
-
-    remote_path = get_project_remote(project, bucket_name)
-    if path:
-        remote_path = f"{remote_path}/{path}"
-
-    cmd = ["rclone", "ls", remote_path]
-    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
-    return result.stdout.splitlines()
@@ -1,14 +1,11 @@
-"""rclone configuration management for Basic Memory Cloud.
-
-This module provides simplified rclone configuration for SPEC-20.
-Uses a single "basic-memory-cloud" remote for all operations.
-"""
+"""rclone configuration management for Basic Memory Cloud."""

 import configparser
 import os
 import shutil
+import subprocess
 from pathlib import Path
-from typing import Optional
+from typing import Dict, List, Optional

 from rich.console import Console

@@ -21,6 +18,64 @@ class RcloneConfigError(Exception):
    pass


+class RcloneMountProfile:
+    """Mount profile with optimized settings."""
+
+    def __init__(
+        self,
+        name: str,
+        cache_time: str,
+        poll_interval: str,
+        attr_timeout: str,
+        write_back: str,
+        description: str,
+        extra_args: Optional[List[str]] = None,
+    ):
+        self.name = name
+        self.cache_time = cache_time
+        self.poll_interval = poll_interval
+        self.attr_timeout = attr_timeout
+        self.write_back = write_back
+        self.description = description
+        self.extra_args = extra_args or []
+
+
+# Mount profiles based on SPEC-7 Phase 4 testing
+MOUNT_PROFILES = {
+    "fast": RcloneMountProfile(
+        name="fast",
+        cache_time="5s",
+        poll_interval="3s",
+        attr_timeout="3s",
+        write_back="1s",
+        description="Ultra-fast development (5s sync, higher bandwidth)",
+    ),
+    "balanced": RcloneMountProfile(
+        name="balanced",
+        cache_time="10s",
+        poll_interval="5s",
+        attr_timeout="5s",
+        write_back="2s",
+        description="Fast development (10-15s sync, recommended)",
+    ),
+    "safe": RcloneMountProfile(
+        name="safe",
+        cache_time="15s",
+        poll_interval="10s",
+        attr_timeout="10s",
+        write_back="5s",
+        description="Conflict-aware mount with backup",
+        extra_args=[
+            "--conflict-suffix",
+            ".conflict-{DateTimeExt}",
+            "--backup-dir",
+            "~/.basic-memory/conflicts",
+            "--track-renames",
+        ],
+    ),
+}
+
+
 def get_rclone_config_path() -> Path:
    """Get the path to rclone configuration file."""
    config_dir = Path.home() / ".config" / "rclone"
@@ -61,50 +116,169 @@ def save_rclone_config(config: configparser.ConfigParser) -> None:
    console.print(f"[dim]Updated rclone config: {config_path}[/dim]")


-def configure_rclone_remote(
+def add_tenant_to_rclone_config(
+    tenant_id: str,
+    bucket_name: str,
    access_key: str,
    secret_key: str,
    endpoint: str = "https://fly.storage.tigris.dev",
    region: str = "auto",
 ) -> str:
-    """Configure single rclone remote named 'basic-memory-cloud'.
+    """Add tenant configuration to rclone config file."""

-    This is the simplified approach from SPEC-20 that uses one remote
-    for all Basic Memory cloud operations (not tenant-specific).
-
-    Args:
-        access_key: S3 access key ID
-        secret_key: S3 secret access key
-        endpoint: S3-compatible endpoint URL
-        region: S3 region (default: auto)
-
-    Returns:
-        The remote name: "basic-memory-cloud"
-    """
    # Backup existing config
    backup_rclone_config()

    # Load existing config
    config = load_rclone_config()

-    # Single remote name (not tenant-specific)
-    REMOTE_NAME = "basic-memory-cloud"
+    # Create section name
+    section_name = f"basic-memory-{tenant_id}"

-    # Add/update the remote section
-    if not config.has_section(REMOTE_NAME):
-        config.add_section(REMOTE_NAME)
+    # Add/update the tenant section
+    if not config.has_section(section_name):
+        config.add_section(section_name)
+
+    config.set(section_name, "type", "s3")
+    config.set(section_name, "provider", "Other")
+    config.set(section_name, "access_key_id", access_key)
+    config.set(section_name, "secret_access_key", secret_key)
+    config.set(section_name, "endpoint", endpoint)
+    config.set(section_name, "region", region)

-    config.set(REMOTE_NAME, "type", "s3")
-    config.set(REMOTE_NAME, "provider", "Other")
-    config.set(REMOTE_NAME, "access_key_id", access_key)
-    config.set(REMOTE_NAME, "secret_access_key", secret_key)
-    config.set(REMOTE_NAME, "endpoint", endpoint)
-    config.set(REMOTE_NAME, "region", region)
-    # Prevent unnecessary encoding of filenames (only encode slashes and invalid UTF-8)
-    # This prevents files with spaces like "Hello World.md" from being quoted
-    config.set(REMOTE_NAME, "encoding", "Slash,InvalidUtf8")
    # Save updated config
    save_rclone_config(config)

-    console.print(f"[green]Configured rclone remote: {REMOTE_NAME}[/green]")
-    return REMOTE_NAME
+    console.print(f"[green]✓ Added tenant {tenant_id} to rclone config[/green]")
+    return section_name
+
+
+def remove_tenant_from_rclone_config(tenant_id: str) -> bool:
+    """Remove tenant configuration from rclone config."""
+    config = load_rclone_config()
+    section_name = f"basic-memory-{tenant_id}"
+
+    if config.has_section(section_name):
+        backup_rclone_config()
+        config.remove_section(section_name)
+        save_rclone_config(config)
+        console.print(f"[green]✓ Removed tenant {tenant_id} from rclone config[/green]")
+        return True
+
+    return False
+
+
+def get_default_mount_path(tenant_id: str) -> Path:
+    """Get default mount path for a tenant."""
+    return Path.home() / f"basic-memory-{tenant_id}"
+
+
+def build_mount_command(
+    tenant_id: str, bucket_name: str, mount_path: Path, profile: RcloneMountProfile
+) -> List[str]:
+    """Build rclone mount command with optimized settings."""
+
+    rclone_remote = f"basic-memory-{tenant_id}:{bucket_name}"
+
+    cmd = [
+        "rclone",
+        "nfsmount",
+        rclone_remote,
+        str(mount_path),
+        "--vfs-cache-mode",
+        "writes",
+        "--dir-cache-time",
+        profile.cache_time,
+        "--vfs-cache-poll-interval",
+        profile.poll_interval,
+        "--attr-timeout",
+        profile.attr_timeout,
+        "--vfs-write-back",
+        profile.write_back,
+        "--daemon",
+    ]
+
+    # Add profile-specific extra arguments
+    cmd.extend(profile.extra_args)
+
+    return cmd
+
+
+def is_path_mounted(mount_path: Path) -> bool:
+    """Check if a path is currently mounted."""
+    if not mount_path.exists():
+        return False
+
+    try:
+        # Check if mount point is actually mounted by looking for mount table entry
+        result = subprocess.run(["mount"], capture_output=True, text=True, check=False)
+
+        if result.returncode == 0:
+            # Look for our mount path in mount output
+            mount_str = str(mount_path.resolve())
+            return mount_str in result.stdout
+
+        return False
+    except Exception:
+        return False
+
+
+def get_rclone_processes() -> List[Dict[str, str]]:
+    """Get list of running rclone processes."""
+    try:
+        # Use ps to find rclone processes
+        result = subprocess.run(
+            ["ps", "-eo", "pid,args"], capture_output=True, text=True, check=False
+        )
+
+        processes = []
+        if result.returncode == 0:
+            for line in result.stdout.split("\n"):
+                if "rclone" in line and "basic-memory" in line:
+                    parts = line.strip().split(None, 1)
+                    if len(parts) >= 2:
+                        processes.append({"pid": parts[0], "command": parts[1]})
+
+        return processes
+    except Exception:
+        return []
+
+
+def kill_rclone_process(pid: str) -> bool:
+    """Kill a specific rclone process."""
+    try:
+        subprocess.run(["kill", pid], check=True)
+        console.print(f"[green]✓ Killed rclone process {pid}[/green]")
+        return True
+    except subprocess.CalledProcessError:
+        console.print(f"[red]✗ Failed to kill rclone process {pid}[/red]")
+        return False
+
+
+def unmount_path(mount_path: Path) -> bool:
+    """Unmount a mounted path."""
+    if not is_path_mounted(mount_path):
+        return True
+
+    try:
+        subprocess.run(["umount", str(mount_path)], check=True)
+        console.print(f"[green]✓ Unmounted {mount_path}[/green]")
+        return True
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]✗ Failed to unmount {mount_path}: {e}[/red]")
+        return False
+
+
+def cleanup_orphaned_rclone_processes() -> int:
+    """Clean up orphaned rclone processes for basic-memory."""
+    processes = get_rclone_processes()
+    killed_count = 0
+
+    for proc in processes:
+        console.print(
+            f"[yellow]Found rclone process: {proc['pid']} - {proc['command'][:80]}...[/yellow]"
+        )
+        if kill_rclone_process(proc["pid"]):
+            killed_count += 1
+
+    return killed_count
@@ -1,6 +1,5 @@
 """Cross-platform rclone installation utilities."""

-import os
 import platform
 import shutil
 import subprocess
@@ -59,7 +58,7 @@ def install_rclone_macos() -> None:
        try:
            console.print("[blue]Installing rclone via Homebrew...[/blue]")
            run_command(["brew", "install", "rclone"])
-            console.print("[green]rclone installed via Homebrew[/green]")
+            console.print("[green]✓ rclone installed via Homebrew[/green]")
            return
        except RcloneInstallError:
            console.print(
@@ -70,7 +69,7 @@ def install_rclone_macos() -> None:
    console.print("[blue]Installing rclone via official script...[/blue]")
    try:
        run_command(["sh", "-c", "curl https://rclone.org/install.sh | sudo bash"])
-        console.print("[green]rclone installed via official script[/green]")
+        console.print("[green]✓ rclone installed via official script[/green]")
    except RcloneInstallError:
        raise RcloneInstallError(
            "Failed to install rclone. Please install manually: brew install rclone"
@@ -84,7 +83,7 @@ def install_rclone_linux() -> None:
        try:
            console.print("[blue]Installing rclone via snap...[/blue]")
            run_command(["sudo", "snap", "install", "rclone"])
-            console.print("[green]rclone installed via snap[/green]")
+            console.print("[green]✓ rclone installed via snap[/green]")
            return
        except RcloneInstallError:
            console.print("[yellow]Snap installation failed, trying apt...[/yellow]")
@@ -95,7 +94,7 @@ def install_rclone_linux() -> None:
            console.print("[blue]Installing rclone via apt...[/blue]")
            run_command(["sudo", "apt", "update"])
            run_command(["sudo", "apt", "install", "-y", "rclone"])
-            console.print("[green]rclone installed via apt[/green]")
+            console.print("[green]✓ rclone installed via apt[/green]")
            return
        except RcloneInstallError:
            console.print("[yellow]apt installation failed, trying official script...[/yellow]")
@@ -104,7 +103,7 @@ def install_rclone_linux() -> None:
    console.print("[blue]Installing rclone via official script...[/blue]")
    try:
        run_command(["sh", "-c", "curl https://rclone.org/install.sh | sudo bash"])
-        console.print("[green]rclone installed via official script[/green]")
+        console.print("[green]✓ rclone installed via official script[/green]")
    except RcloneInstallError:
        raise RcloneInstallError(
            "Failed to install rclone. Please install manually: sudo snap install rclone"
@@ -117,16 +116,8 @@ def install_rclone_windows() -> None:
    if shutil.which("winget"):
        try:
            console.print("[blue]Installing rclone via winget...[/blue]")
-            run_command(
-                [
-                    "winget",
-                    "install",
-                    "Rclone.Rclone",
-                    "--accept-source-agreements",
-                    "--accept-package-agreements",
-                ]
-            )
-            console.print("[green]rclone installed via winget[/green]")
+            run_command(["winget", "install", "Rclone.Rclone"])
+            console.print("[green]✓ rclone installed via winget[/green]")
            return
        except RcloneInstallError:
            console.print("[yellow]winget installation failed, trying chocolatey...[/yellow]")
@@ -136,7 +127,7 @@ def install_rclone_windows() -> None:
        try:
            console.print("[blue]Installing rclone via chocolatey...[/blue]")
            run_command(["choco", "install", "rclone", "-y"])
-            console.print("[green]rclone installed via chocolatey[/green]")
+            console.print("[green]✓ rclone installed via chocolatey[/green]")
            return
        except RcloneInstallError:
            console.print("[yellow]chocolatey installation failed, trying scoop...[/yellow]")
@@ -146,30 +137,16 @@ def install_rclone_windows() -> None:
        try:
            console.print("[blue]Installing rclone via scoop...[/blue]")
            run_command(["scoop", "install", "rclone"])
-            console.print("[green]rclone installed via scoop[/green]")
+            console.print("[green]✓ rclone installed via scoop[/green]")
            return
        except RcloneInstallError:
            console.print("[yellow]scoop installation failed[/yellow]")

-    # No package manager available - provide detailed instructions
-    error_msg = (
-        "Could not install rclone automatically.\n\n"
-        "Windows requires a package manager to install rclone. Options:\n\n"
-        "1. Install winget (recommended, built into Windows 11):\n"
-        "   - Windows 11: Already installed\n"
-        "   - Windows 10: Install 'App Installer' from Microsoft Store\n"
-        "   - Then run: bm cloud setup\n\n"
-        "2. Install chocolatey:\n"
-        "   - Visit: https://chocolatey.org/install\n"
-        "   - Then run: bm cloud setup\n\n"
-        "3. Install scoop:\n"
-        "   - Visit: https://scoop.sh\n"
-        "   - Then run: bm cloud setup\n\n"
-        "4. Manual installation:\n"
-        "   - Download from: https://rclone.org/downloads/\n"
-        "   - Extract and add to PATH\n"
+    # No package manager available
+    raise RcloneInstallError(
+        "Could not install rclone automatically. Please install a package manager "
+        "(winget, chocolatey, or scoop) or install rclone manually from https://rclone.org/downloads/"
    )
-    raise RcloneInstallError(error_msg)


 def install_rclone(platform_override: Optional[str] = None) -> None:
@@ -188,7 +165,6 @@ def install_rclone(platform_override: Optional[str] = None) -> None:
            install_rclone_linux()
        elif platform_name == "windows":
            install_rclone_windows()
-            refresh_windows_path()
        else:
            raise RcloneInstallError(f"Unsupported platform: {platform_name}")

@@ -196,7 +172,7 @@ def install_rclone(platform_override: Optional[str] = None) -> None:
        if not is_rclone_installed():
            raise RcloneInstallError("rclone installation completed but command not found in PATH")

-        console.print("[green]rclone installation completed successfully[/green]")
+        console.print("[green]✓ rclone installation completed successfully[/green]")

    except RcloneInstallError:
        raise
@@ -204,47 +180,6 @@ def install_rclone(platform_override: Optional[str] = None) -> None:
        raise RcloneInstallError(f"Unexpected error during installation: {e}") from e


-def refresh_windows_path() -> None:
-    """Refresh the Windows PATH environment variable for the current session."""
-    if platform.system().lower() != "windows":
-        return
-
-    # Importing here after performing platform detection. Also note that we have to ignore pylance/pyright
-    # warnings about winreg attributes so that "errors" don't appear on non-Windows platforms.
-    import winreg
-
-    user_key_path = r"Environment"
-    system_key_path = r"System\CurrentControlSet\Control\Session Manager\Environment"
-    new_path = ""
-
-    # Read user PATH
-    try:
-        reg_key = winreg.OpenKey(winreg.HKEY_CURRENT_USER, user_key_path, 0, winreg.KEY_READ)  # type: ignore[reportAttributeAccessIssue]
-        user_path, _ = winreg.QueryValueEx(reg_key, "PATH")  # type: ignore[reportAttributeAccessIssue]
-        winreg.CloseKey(reg_key)  # type: ignore[reportAttributeAccessIssue]
-    except Exception:
-        user_path = ""
-
-    # Read system PATH
-    try:
-        reg_key = winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, system_key_path, 0, winreg.KEY_READ)  # type: ignore[reportAttributeAccessIssue]
-        system_path, _ = winreg.QueryValueEx(reg_key, "PATH")  # type: ignore[reportAttributeAccessIssue]
-        winreg.CloseKey(reg_key)  # type: ignore[reportAttributeAccessIssue]
-    except Exception:
-        system_path = ""
-
-    # Merge user and system PATHs (system first, then user)
-    if system_path and user_path:
-        new_path = system_path + ";" + user_path
-    elif system_path:
-        new_path = system_path
-    elif user_path:
-        new_path = user_path
-
-    if new_path:
-        os.environ["PATH"] = new_path
-
-
 def get_rclone_version() -> Optional[str]:
    """Get the installed rclone version."""
    if not is_rclone_installed():
@@ -1,233 +0,0 @@
-"""WebDAV upload functionality for basic-memory projects."""
-
-import os
-from pathlib import Path
-
-import aiofiles
-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"}
-
-
-async def upload_path(
-    local_path: Path,
-    project_name: str,
-    verbose: bool = False,
-    use_gitignore: bool = True,
-    dry_run: bool = False,
-) -> bool:
-    """
-    Upload a file or directory to cloud project via WebDAV.
-
-    Args:
-        local_path: Path to local file or directory
-        project_name: Name of cloud project (destination)
-        verbose: Show detailed information about filtering and upload
-        use_gitignore: If False, skip .gitignore patterns (still use .bmignore)
-        dry_run: If True, show what would be uploaded without uploading
-
-    Returns:
-        True if upload succeeded, False otherwise
-    """
-    try:
-        # Resolve path
-        local_path = local_path.resolve()
-
-        # Check if path exists
-        if not local_path.exists():
-            print(f"Error: Path does not exist: {local_path}")
-            return False
-
-        # Get files to upload
-        if local_path.is_file():
-            files_to_upload = [(local_path, local_path.name)]
-            if verbose:
-                print(f"Uploading single file: {local_path.name}")
-        else:
-            files_to_upload = _get_files_to_upload(local_path, verbose, use_gitignore)
-
-        if not files_to_upload:
-            print("No files found to upload")
-            if verbose:
-                print(
-                    "\nTip: Use --verbose to see which files are being filtered, "
-                    "or --no-gitignore to skip .gitignore patterns"
-                )
-            return True
-
-        print(f"Found {len(files_to_upload)} file(s) to upload")
-
-        # Calculate total size
-        total_bytes = sum(file_path.stat().st_size for file_path, _ in files_to_upload)
-        skipped_count = 0
-
-        # If dry run, just show what would be uploaded
-        if dry_run:
-            print("\nFiles that would be uploaded:")
-            for file_path, relative_path in files_to_upload:
-                # Skip archive files
-                if _is_archive_file(file_path):
-                    print(f"  [SKIP] {relative_path} (archive file)")
-                    skipped_count += 1
-                    continue
-
-                size = file_path.stat().st_size
-                if size < 1024:
-                    size_str = f"{size} bytes"
-                elif size < 1024 * 1024:
-                    size_str = f"{size / 1024:.1f} KB"
-                else:
-                    size_str = f"{size / (1024 * 1024):.1f} MB"
-                print(f"  {relative_path} ({size_str})")
-        else:
-            # Upload files using httpx
-            async with get_client() as client:
-                for i, (file_path, relative_path) in enumerate(files_to_upload, 1):
-                    # Skip archive files (zip, tar, gz, etc.)
-                    if _is_archive_file(file_path):
-                        print(
-                            f"Skipping archive file: {relative_path} ({i}/{len(files_to_upload)})"
-                        )
-                        skipped_count += 1
-                        continue
-
-                    # Build remote path: /webdav/{project_name}/{relative_path}
-                    remote_path = f"/webdav/{project_name}/{relative_path}"
-                    print(f"Uploading {relative_path} ({i}/{len(files_to_upload)})")
-
-                    # Get file modification time
-                    file_stat = file_path.stat()
-                    mtime = int(file_stat.st_mtime)
-
-                    # Read file content asynchronously
-                    async with aiofiles.open(file_path, "rb") as f:
-                        content = await f.read()
-
-                    # Upload via HTTP PUT to WebDAV endpoint with mtime header
-                    # Using X-OC-Mtime (ownCloud/Nextcloud standard)
-                    response = await call_put(
-                        client, remote_path, content=content, headers={"X-OC-Mtime": str(mtime)}
-                    )
-                    response.raise_for_status()
-
-        # Format total size based on magnitude
-        if total_bytes < 1024:
-            size_str = f"{total_bytes} bytes"
-        elif total_bytes < 1024 * 1024:
-            size_str = f"{total_bytes / 1024:.1f} KB"
-        else:
-            size_str = f"{total_bytes / (1024 * 1024):.1f} MB"
-
-        uploaded_count = len(files_to_upload) - skipped_count
-        if dry_run:
-            print(f"\nTotal: {uploaded_count} file(s) ({size_str})")
-            if skipped_count > 0:
-                print(f"  Would skip {skipped_count} archive file(s)")
-        else:
-            print(f"✓ Upload complete: {uploaded_count} file(s) ({size_str})")
-            if skipped_count > 0:
-                print(f"  Skipped {skipped_count} archive file(s)")
-
-        return True
-
-    except httpx.HTTPStatusError as e:
-        print(f"Upload failed: HTTP {e.response.status_code} - {e.response.text}")
-        return False
-    except Exception as e:
-        print(f"Upload failed: {e}")
-        return False
-
-
-def _is_archive_file(file_path: Path) -> bool:
-    """
-    Check if a file is an archive file based on its extension.
-
-    Args:
-        file_path: Path to the file to check
-
-    Returns:
-        True if file is an archive, False otherwise
-    """
-    return file_path.suffix.lower() in ARCHIVE_EXTENSIONS
-
-
-def _get_files_to_upload(
-    directory: Path, verbose: bool = False, use_gitignore: bool = True
-) -> list[tuple[Path, str]]:
-    """
-    Get list of files to upload from directory.
-
-    Uses .bmignore and optionally .gitignore patterns for filtering.
-
-    Args:
-        directory: Directory to scan
-        verbose: Show detailed filtering information
-        use_gitignore: If False, skip .gitignore patterns (still use .bmignore)
-
-    Returns:
-        List of (absolute_path, relative_path) tuples
-    """
-    files = []
-    ignored_files = []
-
-    # Load ignore patterns from .bmignore and optionally .gitignore
-    ignore_patterns = load_gitignore_patterns(directory, use_gitignore=use_gitignore)
-
-    if verbose:
-        gitignore_path = directory / ".gitignore"
-        gitignore_exists = gitignore_path.exists() and use_gitignore
-        print(f"\nScanning directory: {directory}")
-        print("Using .bmignore: Yes")
-        print(f"Using .gitignore: {'Yes' if gitignore_exists else 'No'}")
-        print(f"Ignore patterns loaded: {len(ignore_patterns)}")
-        if ignore_patterns and len(ignore_patterns) <= 20:
-            print(f"Patterns: {', '.join(sorted(ignore_patterns))}")
-        print()
-
-    # Walk through directory
-    for root, dirs, filenames in os.walk(directory):
-        root_path = Path(root)
-
-        # Filter directories based on ignore patterns
-        filtered_dirs = []
-        for d in dirs:
-            dir_path = root_path / d
-            if should_ignore_path(dir_path, directory, ignore_patterns):
-                if verbose:
-                    rel_path = dir_path.relative_to(directory)
-                    print(f"  [IGNORED DIR] {rel_path}/")
-            else:
-                filtered_dirs.append(d)
-        dirs[:] = filtered_dirs
-
-        # Process files
-        for filename in filenames:
-            file_path = root_path / filename
-
-            # Calculate relative path for display/remote
-            rel_path = file_path.relative_to(directory)
-            remote_path = str(rel_path).replace("\\", "/")
-
-            # Check if file should be ignored
-            if should_ignore_path(file_path, directory, ignore_patterns):
-                ignored_files.append(remote_path)
-                if verbose:
-                    print(f"  [IGNORED] {remote_path}")
-                continue
-
-            if verbose:
-                print(f"  [INCLUDE] {remote_path}")
-
-            files.append((file_path, remote_path))
-
-    if verbose:
-        print("\nSummary:")
-        print(f"  Files to upload: {len(files)}")
-        print(f"  Files ignored: {len(ignored_files)}")
-
-    return files
@@ -1,124 +0,0 @@
-"""Upload CLI commands for basic-memory projects."""
-
-import asyncio
-from pathlib import Path
-
-import typer
-from rich.console import Console
-
-from basic_memory.cli.app import cloud_app
-from basic_memory.cli.commands.cloud.cloud_utils import (
-    create_cloud_project,
-    project_exists,
-    sync_project,
-)
-from basic_memory.cli.commands.cloud.upload import upload_path
-
-console = Console()
-
-
-@cloud_app.command("upload")
-def upload(
-    path: Path = typer.Argument(
-        ...,
-        help="Path to local file or directory to upload",
-        exists=True,
-        readable=True,
-        resolve_path=True,
-    ),
-    project: str = typer.Option(
-        ...,
-        "--project",
-        "-p",
-        help="Cloud project name (destination)",
-    ),
-    create_project: bool = typer.Option(
-        False,
-        "--create-project",
-        "-c",
-        help="Create project if it doesn't exist",
-    ),
-    sync: bool = typer.Option(
-        True,
-        "--sync/--no-sync",
-        help="Sync project after upload (default: true)",
-    ),
-    verbose: bool = typer.Option(
-        False,
-        "--verbose",
-        "-v",
-        help="Show detailed information about file filtering and upload",
-    ),
-    no_gitignore: bool = typer.Option(
-        False,
-        "--no-gitignore",
-        help="Skip .gitignore patterns (still respects .bmignore)",
-    ),
-    dry_run: bool = typer.Option(
-        False,
-        "--dry-run",
-        help="Show what would be uploaded without actually uploading",
-    ),
-) -> None:
-    """Upload local files or directories to cloud project via WebDAV.
-
-    Examples:
-      bm cloud upload ~/my-notes --project research
-      bm cloud upload notes.md --project research --create-project
-      bm cloud upload ~/docs --project work --no-sync
-      bm cloud upload ./history --project proto --verbose
-      bm cloud upload ./notes --project work --no-gitignore
-      bm cloud upload ./files --project test --dry-run
-    """
-
-    async def _upload():
-        # Check if project exists
-        if not await project_exists(project):
-            if create_project:
-                console.print(f"[blue]Creating cloud project '{project}'...[/blue]")
-                try:
-                    await create_cloud_project(project)
-                    console.print(f"[green]Created project '{project}'[/green]")
-                except Exception as e:
-                    console.print(f"[red]Failed to create project: {e}[/red]")
-                    raise typer.Exit(1)
-            else:
-                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"  2. Use --create-project flag to create automatically"
-                )
-                raise typer.Exit(1)
-
-        # Perform upload (or dry run)
-        if dry_run:
-            console.print(
-                f"[yellow]DRY RUN: Showing what would be uploaded to '{project}'[/yellow]"
-            )
-        else:
-            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
-        )
-        if not success:
-            console.print("[red]Upload failed[/red]")
-            raise typer.Exit(1)
-
-        if dry_run:
-            console.print("[yellow]DRY RUN complete - no files were uploaded[/yellow]")
-        else:
-            console.print(f"[green]Successfully uploaded to '{project}'[/green]")
-
-        # Sync project if requested (skip on dry run)
-        # Force full scan after bisync to ensure database is up-to-date with synced files
-        if sync and not dry_run:
-            console.print(f"[blue]Syncing project '{project}'...[/blue]")
-            try:
-                await sync_project(project, force_full=True)
-            except Exception as e:
-                console.print(f"[yellow]Warning: Sync failed: {e}[/yellow]")
-                console.print("[dim]Files uploaded but may not be indexed yet[/dim]")
-
-    asyncio.run(_upload())
@@ -1,51 +0,0 @@
-"""utility functions for commands"""
-
-from typing import Optional
-
-from mcp.server.fastmcp.exceptions import ToolError
-import typer
-
-from rich.console import Console
-
-from basic_memory.mcp.async_client import get_client
-
-from basic_memory.mcp.tools.utils import call_post, call_get
-from basic_memory.mcp.project_context import get_active_project
-from basic_memory.schemas import ProjectInfoResponse
-
-console = Console()
-
-
-async def run_sync(project: Optional[str] = None, force_full: bool = False):
-    """Run sync operation via API endpoint.
-
-    Args:
-        project: Optional project name
-        force_full: If True, force a full scan bypassing watermark optimization
-    """
-
-    try:
-        async with get_client() as client:
-            project_item = await get_active_project(client, project, None)
-            url = f"{project_item.project_url}/project/sync"
-            if force_full:
-                url += "?force_full=true"
-            response = await call_post(client, url)
-            data = response.json()
-            console.print(f"[green]{data['message']}[/green]")
-    except (ToolError, ValueError) as e:
-        console.print(f"[red]Sync failed: {e}[/red]")
-        raise typer.Exit(1)
-
-
-async def get_project_info(project: str):
-    """Get project information via API endpoint."""
-
-    try:
-        async with get_client() 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())
-    except (ToolError, ValueError) as e:
-        console.print(f"[red]Sync failed: {e}[/red]")
-        raise typer.Exit(1)
@@ -37,8 +37,8 @@ def reset(
        logger.info("Database reset complete")

        if reindex:
-            # Run database sync directly
-            from basic_memory.cli.commands.command_utils import run_sync
+            # Import and run sync
+            from basic_memory.cli.commands.sync import sync

            logger.info("Rebuilding search index from filesystem...")
-            asyncio.run(run_sync(project=None))
+            sync(watch=False)  # pyright: ignore
@@ -17,78 +17,75 @@ import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
 # Import prompts to register them
 import basic_memory.mcp.prompts  # noqa: F401  # pragma: no cover
 from loguru import logger
-import threading
-from basic_memory.services.initialization import initialize_file_sync

-config = ConfigManager().config

-if not config.cloud_mode_enabled:
+@app.command()
+def mcp(
+    transport: str = typer.Option("stdio", help="Transport type: stdio, streamable-http, or sse"),
+    host: str = typer.Option(
+        "0.0.0.0", help="Host for HTTP transports (use 0.0.0.0 to allow external connections)"
+    ),
+    port: int = typer.Option(8000, help="Port for HTTP transports"),
+    path: str = typer.Option("/mcp", help="Path prefix for streamable-http transport"),
+    project: Optional[str] = typer.Option(None, help="Restrict MCP server to single project"),
+):  # pragma: no cover
+    """Run the MCP server with configurable transport options.

-    @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:

-        This command starts an MCP server using one of three transport options:
+    - stdio: Standard I/O (good for local usage)
+    - streamable-http: Recommended for web deployments (default)
+    - sse: Server-Sent Events (for compatibility with existing clients)
+    """

-        - stdio: Standard I/O (good for local usage)
-        - streamable-http: Recommended for web deployments (default)
-        - sse: Server-Sent Events (for compatibility with existing clients)
-        """
+    # Validate and set project constraint if specified
+    if project:
+        config_manager = ConfigManager()
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)

-        # 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}")

-            # 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}")
+    # Use unified thread-based sync approach for both transports
+    import threading
+    from basic_memory.services.initialization import initialize_file_sync

-        app_config = ConfigManager().config
+    app_config = ConfigManager().config

-        def run_file_sync():
-            """Run file sync in a separate thread with its own event loop."""
-            loop = asyncio.new_event_loop()
-            asyncio.set_event_loop(loop)
-            try:
-                loop.run_until_complete(initialize_file_sync(app_config))
-            except Exception as e:
-                logger.error(f"File sync error: {e}", err=True)
-            finally:
-                loop.close()
+    def run_file_sync():
+        """Run file sync in a separate thread with its own event loop."""
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            loop.run_until_complete(initialize_file_sync(app_config))
+        except Exception as e:
+            logger.error(f"File sync error: {e}", err=True)
+        finally:
+            loop.close()

-        logger.info(f"Sync changes enabled: {app_config.sync_changes}")
-        if app_config.sync_changes:
-            # Start the sync thread
-            sync_thread = threading.Thread(target=run_file_sync, daemon=True)
-            sync_thread.start()
-            logger.info("Started file sync in background")
+    logger.info(f"Sync changes enabled: {app_config.sync_changes}")
+    if app_config.sync_changes:
+        # Start the sync thread
+        sync_thread = threading.Thread(target=run_file_sync, daemon=True)
+        sync_thread.start()
+        logger.info("Started file sync in background")

-        # Now run the MCP server (blocks)
-        logger.info(f"Starting MCP server with {transport.upper()} transport")
+    # Now run the MCP server (blocks)
+    logger.info(f"Starting MCP server with {transport.upper()} transport")

-        if transport == "stdio":
-            mcp_server.run(
-                transport=transport,
-            )
-        elif transport == "streamable-http" or transport == "sse":
-            mcp_server.run(
-                transport=transport,
-                host=host,
-                port=port,
-                path=path,
-                log_level="INFO",
-            )
+    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",
+        )
@@ -9,33 +9,22 @@ 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 get_project_info
-from basic_memory.config import ConfigManager
+from basic_memory.mcp.resources.project_info import project_info
 import json
 from datetime import datetime

 from rich.panel import Panel
-from basic_memory.mcp.async_client import get_client
+from rich.tree import Tree
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.project_info import ProjectList
 from basic_memory.mcp.tools.utils import call_post
 from basic_memory.schemas.project_info import ProjectStatusResponse
 from basic_memory.mcp.tools.utils import call_delete
 from basic_memory.mcp.tools.utils import call_put
-from basic_memory.utils import generate_permalink, normalize_project_path
+from basic_memory.utils import generate_permalink
 from basic_memory.mcp.tools.utils import call_patch

-# Import rclone commands for project sync
-from basic_memory.cli.commands.cloud.rclone_commands import (
-    SyncProject,
-    RcloneError,
-    project_sync,
-    project_bisync,
-    project_check,
-    project_ls,
-)
-from basic_memory.cli.commands.cloud.bisync_commands import get_mount_info
-
 console = Console()

 # Create a project subcommand
@@ -53,50 +42,20 @@ def format_path(path: str) -> str:

@project_app.command("list")
 def list_projects() -> None:
-    """List all Basic Memory projects."""
-
-    async def _list_projects():
-        async with get_client() as client:
-            response = await call_get(client, "/projects/projects")
-            return ProjectList.model_validate(response.json())
-
+    """List all configured projects."""
+    # Use API to list projects
    try:
-        result = asyncio.run(_list_projects())
-        config = ConfigManager().config
+        response = asyncio.run(call_get(client, "/projects/projects"))
+        result = ProjectList.model_validate(response.json())

        table = Table(title="Basic Memory Projects")
        table.add_column("Name", style="cyan")
        table.add_column("Path", style="green")
-
-        # Add Local Path column if in cloud mode
-        if config.cloud_mode_enabled:
-            table.add_column("Local Path", style="yellow", no_wrap=True, overflow="fold")
-
-        # Show Default column in local mode or if default_project_mode is enabled in cloud mode
-        show_default_column = not config.cloud_mode_enabled or config.default_project_mode
-        if show_default_column:
-            table.add_column("Default", style="magenta")
+        table.add_column("Default", style="magenta")

        for project in result.projects:
-            is_default = "[X]" if project.is_default else ""
-            normalized_path = normalize_project_path(project.path)
-
-            # Build row based on mode
-            row = [project.name, format_path(normalized_path)]
-
-            # Add local path if in cloud mode
-            if config.cloud_mode_enabled:
-                local_path = ""
-                if project.name in config.cloud_projects:
-                    local_path = config.cloud_projects[project.name].local_path or ""
-                    local_path = format_path(local_path)
-                row.append(local_path)
-
-            # Add default indicator if showing default column
-            if show_default_column:
-                row.append(is_default)
-
-            table.add_row(*row)
+            is_default = "✓" if project.is_default else ""
+            table.add_row(project.name, format_path(project.path), is_default)

        console.print(table)
    except Exception as e:
@@ -107,259 +66,80 @@ def list_projects() -> None:
@project_app.command("add")
 def add_project(
    name: str = typer.Argument(..., help="Name of the project"),
-    path: str = typer.Argument(
-        None, help="Path to the project directory (required for local mode)"
-    ),
-    local_path: str = typer.Option(
-        None, "--local-path", help="Local sync path for cloud mode (optional)"
-    ),
+    path: str = typer.Argument(..., help="Path to the project directory"),
    set_default: bool = typer.Option(False, "--default", help="Set as default project"),
 ) -> None:
-    """Add a new project.
-
-    Cloud mode examples:\n
-        bm project add research                           # No local sync\n
-        bm project add research --local-path ~/docs       # With local sync\n
-
-    Local mode example:\n
-        bm project add research ~/Documents/research
-    """
-    config = ConfigManager().config
-
-    # Resolve local sync path early (needed for both cloud and local mode)
-    local_sync_path: str | None = None
-    if local_path:
-        local_sync_path = Path(os.path.abspath(os.path.expanduser(local_path))).as_posix()
-
-    if config.cloud_mode_enabled:
-        # Cloud mode: path auto-generated from name, local sync is optional
-
-        async def _add_project():
-            async with get_client() as client:
-                data = {
-                    "name": name,
-                    "path": generate_permalink(name),
-                    "local_sync_path": local_sync_path,
-                    "set_default": set_default,
-                }
-                response = await call_post(client, "/projects/projects", json=data)
-                return ProjectStatusResponse.model_validate(response.json())
-    else:
-        # Local mode: path is required
-        if path is None:
-            console.print("[red]Error: path argument is required in local mode[/red]")
-            raise typer.Exit(1)
-
-        # Resolve to absolute path
-        resolved_path = Path(os.path.abspath(os.path.expanduser(path))).as_posix()
-
-        async def _add_project():
-            async with get_client() as client:
-                data = {"name": name, "path": resolved_path, "set_default": set_default}
-                response = await call_post(client, "/projects/projects", json=data)
-                return ProjectStatusResponse.model_validate(response.json())
+    """Add a new project."""
+    # Resolve to absolute path
+    resolved_path = Path(os.path.abspath(os.path.expanduser(path))).as_posix()

    try:
-        result = asyncio.run(_add_project())
+        data = {"name": name, "path": resolved_path, "set_default": set_default}
+
+        response = asyncio.run(call_post(client, "/projects/projects", json=data))
+        result = ProjectStatusResponse.model_validate(response.json())
+
        console.print(f"[green]{result.message}[/green]")
-
-        # Save local sync path to config if in cloud mode
-        if config.cloud_mode_enabled and local_sync_path:
-            from basic_memory.config import CloudProjectConfig
-
-            # Create local directory if it doesn't exist
-            local_dir = Path(local_sync_path)
-            local_dir.mkdir(parents=True, exist_ok=True)
-
-            # Update config with sync path
-            config.cloud_projects[name] = CloudProjectConfig(
-                local_path=local_sync_path,
-                last_sync=None,
-                bisync_initialized=False,
-            )
-            ConfigManager().save_config(config)
-
-            console.print(f"\n[green]Local sync path configured: {local_sync_path}[/green]")
-            console.print("\nNext steps:")
-            console.print(f"  1. Preview: bm project bisync --name {name} --resync --dry-run")
-            console.print(f"  2. Sync: bm project bisync --name {name} --resync")
    except Exception as e:
        console.print(f"[red]Error adding project: {str(e)}[/red]")
        raise typer.Exit(1)

-
-@project_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 project sync-setup research ~/Documents/research
-    """
-    config_manager = ConfigManager()
-    config = config_manager.config
-
-    if not config.cloud_mode_enabled:
-        console.print("[red]Error: sync-setup only available in cloud mode[/red]")
-        raise typer.Exit(1)
-
-    async def _verify_project_exists():
-        """Verify the project exists on cloud by listing all projects."""
-        async with get_client() as client:
-            response = await call_get(client, "/projects/projects")
-            project_list = response.json()
-            project_names = [p["name"] for p in project_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
-        asyncio.run(_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 local config with sync path
-        from basic_memory.config import CloudProjectConfig
-
-        config.cloud_projects[name] = CloudProjectConfig(
-            local_path=resolved_path.as_posix(),
-            last_sync=None,
-            bisync_initialized=False,
-        )
-        config_manager.save_config(config)
-
-        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 project bisync --name {name} --resync --dry-run")
-        console.print(f"  2. Sync: bm project bisync --name {name} --resync")
-    except Exception as e:
-        console.print(f"[red]Error configuring sync: {str(e)}[/red]")
-        raise typer.Exit(1)
+    # Display usage hint
+    console.print("\nTo use this project:")
+    console.print(f"  basic-memory --project={name} <command>")
+    console.print("  # or")
+    console.print(f"  basic-memory project default {name}")


@project_app.command("remove")
 def remove_project(
    name: str = typer.Argument(..., help="Name of the project to remove"),
-    delete_notes: bool = typer.Option(
-        False, "--delete-notes", help="Delete project files from disk"
-    ),
 ) -> None:
-    """Remove a project."""
-
-    async def _remove_project():
-        async with get_client() as client:
-            project_permalink = generate_permalink(name)
-            response = await call_delete(
-                client, f"/projects/{project_permalink}?delete_notes={delete_notes}"
-            )
-            return ProjectStatusResponse.model_validate(response.json())
-
+    """Remove a project from configuration."""
    try:
-        # Get config to check for local sync path and bisync state
-        config = ConfigManager().config
-        local_path = None
-        has_bisync_state = False
+        project_permalink = generate_permalink(name)
+        response = asyncio.run(call_delete(client, f"/projects/{project_permalink}"))
+        result = ProjectStatusResponse.model_validate(response.json())

-        if config.cloud_mode_enabled and name in config.cloud_projects:
-            local_path = config.cloud_projects[name].local_path
-
-            # Check for bisync state
-            from basic_memory.cli.commands.cloud.rclone_commands import get_project_bisync_state
-
-            bisync_state_path = get_project_bisync_state(name)
-            has_bisync_state = bisync_state_path.exists()
-
-        # Remove project from cloud/API
-        result = asyncio.run(_remove_project())
        console.print(f"[green]{result.message}[/green]")
-
-        # Clean up local sync directory if it exists and delete_notes is True
-        if delete_notes and local_path:
-            local_dir = Path(local_path)
-            if local_dir.exists():
-                import shutil
-
-                shutil.rmtree(local_dir)
-                console.print(f"[green]Removed local sync directory: {local_path}[/green]")
-
-        # Clean up bisync state if it exists
-        if has_bisync_state:
-            from basic_memory.cli.commands.cloud.rclone_commands import get_project_bisync_state
-            import shutil
-
-            bisync_state_path = get_project_bisync_state(name)
-            if bisync_state_path.exists():
-                shutil.rmtree(bisync_state_path)
-                console.print("[green]Removed bisync state[/green]")
-
-        # Clean up cloud_projects config entry
-        if config.cloud_mode_enabled and name in config.cloud_projects:
-            del config.cloud_projects[name]
-            ConfigManager().save_config(config)
-
-        # Show informative message if files were not deleted
-        if not delete_notes:
-            if local_path:
-                console.print(f"[yellow]Note: Local files remain at {local_path}[/yellow]")
-
    except Exception as e:
        console.print(f"[red]Error removing project: {str(e)}[/red]")
        raise typer.Exit(1)

+    # Show this message regardless of method used
+    console.print("[yellow]Note: The project files have not been deleted from disk.[/yellow]")
+

@project_app.command("default")
 def set_default_project(
    name: str = typer.Argument(..., help="Name of the project to set as CLI default"),
 ) -> None:
-    """Set the default project when 'config.default_project_mode' is set.
-
-    Note: This command is only available in local mode.
-    """
-    config = ConfigManager().config
-
-    if config.cloud_mode_enabled:
-        console.print("[red]Error: 'default' command is not available in cloud mode[/red]")
-        raise typer.Exit(1)
-
-    async def _set_default():
-        async with get_client() as client:
-            project_permalink = generate_permalink(name)
-            response = await call_put(client, f"/projects/{project_permalink}/default")
-            return ProjectStatusResponse.model_validate(response.json())
-
+    """Set the default project for CLI operations (when no --project flag is specified)."""
    try:
-        result = asyncio.run(_set_default())
+        project_permalink = generate_permalink(name)
+        response = asyncio.run(call_put(client, f"/projects/{project_permalink}/default"))
+        result = ProjectStatusResponse.model_validate(response.json())
+
        console.print(f"[green]{result.message}[/green]")
    except Exception as e:
        console.print(f"[red]Error setting default project: {str(e)}[/red]")
        raise typer.Exit(1)

+    # The API call above updates the config file default
+    console.print(
+        f"[green]CLI commands will now use '{name}' when no --project flag is specified[/green]"
+    )
+

@project_app.command("sync-config")
 def synchronize_projects() -> None:
-    """Synchronize project config between configuration file and database.
-
-    Note: This command is only available in local mode.
-    """
-    config = ConfigManager().config
-
-    if config.cloud_mode_enabled:
-        console.print("[red]Error: 'sync-config' command is not available in cloud mode[/red]")
-        raise typer.Exit(1)
-
-    async def _sync_config():
-        async with get_client() as client:
-            response = await call_post(client, "/projects/config/sync")
-            return ProjectStatusResponse.model_validate(response.json())
+    """Synchronize project config between configuration file and database."""
+    # Call the API to synchronize projects

    try:
-        result = asyncio.run(_sync_config())
+        response = asyncio.run(call_post(client, "/projects/sync"))
+        result = ProjectStatusResponse.model_validate(response.json())
+
        console.print(f"[green]{result.message}[/green]")
    except Exception as e:  # pragma: no cover
        console.print(f"[red]Error synchronizing projects: {str(e)}[/red]")
@@ -371,30 +151,21 @@ def move_project(
    name: str = typer.Argument(..., help="Name of the project to move"),
    new_path: str = typer.Argument(..., help="New absolute path for the project"),
 ) -> None:
-    """Move a project to a new location.
-
-    Note: This command is only available in local mode.
-    """
-    config = ConfigManager().config
-
-    if config.cloud_mode_enabled:
-        console.print("[red]Error: 'move' command is not available in cloud mode[/red]")
-        raise typer.Exit(1)
-
+    """Move a project to a new location."""
    # Resolve to absolute path
    resolved_path = Path(os.path.abspath(os.path.expanduser(new_path))).as_posix()

-    async def _move_project():
-        async with get_client() as client:
-            data = {"path": resolved_path}
-            project_permalink = generate_permalink(name)
-
-            # TODO fix route to use ProjectPathDep
-            response = await call_patch(client, f"/{name}/project/{project_permalink}", json=data)
-            return ProjectStatusResponse.model_validate(response.json())
-
    try:
-        result = asyncio.run(_move_project())
+        data = {"path": resolved_path}
+
+        project_permalink = generate_permalink(name)
+
+        # TODO fix route to use ProjectPathDep
+        response = asyncio.run(
+            call_patch(client, f"/{name}/project/{project_permalink}", json=data)
+        )
+        result = ProjectStatusResponse.model_validate(response.json())
+
        console.print(f"[green]{result.message}[/green]")

        # Show important file movement reminder
@@ -405,7 +176,7 @@ def move_project(
                "[yellow]You must manually move your project files from the old location to:[/yellow]\n"
                f"[cyan]{resolved_path}[/cyan]\n\n"
                "[dim]Basic Memory has only updated the configuration - your files remain in their original location.[/dim]",
-                title="Manual File Movement Required",
+                title="⚠️  Manual File Movement Required",
                border_style="yellow",
                expand=False,
            )
@@ -416,381 +187,35 @@ def move_project(
        raise typer.Exit(1)


-@project_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 project sync --name research
-      bm project sync --name research --dry-run
-    """
-    config = ConfigManager().config
-    if not config.cloud_mode_enabled:
-        console.print("[red]Error: sync only available in cloud mode[/red]")
-        raise typer.Exit(1)
-
-    try:
-        # Get tenant info for bucket name
-        tenant_info = asyncio.run(get_mount_info())
-        bucket_name = tenant_info.bucket_name
-
-        # Get project info
-        async def _get_project():
-            async with get_client() as client:
-                response = await call_get(client, "/projects/projects")
-                projects_list = ProjectList.model_validate(response.json())
-                for proj in projects_list.projects:
-                    if generate_permalink(proj.name) == generate_permalink(name):
-                        return proj
-                return None
-
-        project_data = asyncio.run(_get_project())
-        if not project_data:
-            console.print(f"[red]Error: Project '{name}' not found[/red]")
-            raise typer.Exit(1)
-
-        # Get local_sync_path from cloud_projects config
-        local_sync_path = None
-        if name in config.cloud_projects:
-            local_sync_path = config.cloud_projects[name].local_path
-
-        if not local_sync_path:
-            console.print(f"[red]Error: Project '{name}' has no local_sync_path configured[/red]")
-            console.print(f"\nConfigure sync with: bm project sync-setup {name} ~/path/to/local")
-            raise typer.Exit(1)
-
-        # Create SyncProject
-        sync_project = SyncProject(
-            name=project_data.name,
-            path=normalize_project_path(project_data.path),
-            local_sync_path=local_sync_path,
-        )
-
-        # 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:
-                        permalink = generate_permalink(name)
-                        response = await call_post(
-                            client, f"/{permalink}/project/sync?force_full=true", json={}
-                        )
-                        return response.json()
-
-                try:
-                    result = asyncio.run(_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)
-
-
-@project_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 project bisync --name research --resync  # First time
-      bm project bisync --name research           # Subsequent syncs
-      bm project bisync --name research --dry-run # Preview changes
-    """
-    config = ConfigManager().config
-    if not config.cloud_mode_enabled:
-        console.print("[red]Error: bisync only available in cloud mode[/red]")
-        raise typer.Exit(1)
-
-    try:
-        # Get tenant info for bucket name
-        tenant_info = asyncio.run(get_mount_info())
-        bucket_name = tenant_info.bucket_name
-
-        # Get project info
-        async def _get_project():
-            async with get_client() as client:
-                response = await call_get(client, "/projects/projects")
-                projects_list = ProjectList.model_validate(response.json())
-                for proj in projects_list.projects:
-                    if generate_permalink(proj.name) == generate_permalink(name):
-                        return proj
-                return None
-
-        project_data = asyncio.run(_get_project())
-        if not project_data:
-            console.print(f"[red]Error: Project '{name}' not found[/red]")
-            raise typer.Exit(1)
-
-        # Get local_sync_path from cloud_projects config
-        local_sync_path = None
-        if name in config.cloud_projects:
-            local_sync_path = config.cloud_projects[name].local_path
-
-        if not local_sync_path:
-            console.print(f"[red]Error: Project '{name}' has no local_sync_path configured[/red]")
-            console.print(f"\nConfigure sync with: bm project sync-setup {name} ~/path/to/local")
-            raise typer.Exit(1)
-
-        # Create SyncProject
-        sync_project = SyncProject(
-            name=project_data.name,
-            path=normalize_project_path(project_data.path),
-            local_sync_path=local_sync_path,
-        )
-
-        # 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
-            config.cloud_projects[name].last_sync = datetime.now()
-            config.cloud_projects[name].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:
-                        permalink = generate_permalink(name)
-                        response = await call_post(
-                            client, f"/{permalink}/project/sync?force_full=true", json={}
-                        )
-                        return response.json()
-
-                try:
-                    result = asyncio.run(_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)
-
-
-@project_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 project check --name research
-    """
-    config = ConfigManager().config
-    if not config.cloud_mode_enabled:
-        console.print("[red]Error: check only available in cloud mode[/red]")
-        raise typer.Exit(1)
-
-    try:
-        # Get tenant info for bucket name
-        tenant_info = asyncio.run(get_mount_info())
-        bucket_name = tenant_info.bucket_name
-
-        # Get project info
-        async def _get_project():
-            async with get_client() as client:
-                response = await call_get(client, "/projects/projects")
-                projects_list = ProjectList.model_validate(response.json())
-                for proj in projects_list.projects:
-                    if generate_permalink(proj.name) == generate_permalink(name):
-                        return proj
-                return None
-
-        project_data = asyncio.run(_get_project())
-        if not project_data:
-            console.print(f"[red]Error: Project '{name}' not found[/red]")
-            raise typer.Exit(1)
-
-        # Get local_sync_path from cloud_projects config
-        local_sync_path = None
-        if name in config.cloud_projects:
-            local_sync_path = config.cloud_projects[name].local_path
-
-        if not local_sync_path:
-            console.print(f"[red]Error: Project '{name}' has no local_sync_path configured[/red]")
-            console.print(f"\nConfigure sync with: bm project sync-setup {name} ~/path/to/local")
-            raise typer.Exit(1)
-
-        # Create SyncProject
-        sync_project = SyncProject(
-            name=project_data.name,
-            path=normalize_project_path(project_data.path),
-            local_sync_path=local_sync_path,
-        )
-
-        # 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)
-
-
-@project_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.
-    """
-    from basic_memory.cli.commands.cloud.rclone_commands import get_project_bisync_state
-    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 project bisync --name {name} --resync --dry-run")
-        console.print(f"  2. Sync: bm project bisync --name {name} --resync")
-
-    except Exception as e:
-        console.print(f"[red]Error clearing bisync state: {str(e)}[/red]")
-        raise typer.Exit(1)
-
-
-@project_app.command("ls")
-def ls_project_command(
-    name: str = typer.Option(..., "--name", help="Project name to list files from"),
-    path: str = typer.Argument(None, help="Path within project (optional)"),
-) -> None:
-    """List files in remote project.
-
-    Examples:
-      bm project ls --name research
-      bm project ls --name research subfolder
-    """
-    config = ConfigManager().config
-    if not config.cloud_mode_enabled:
-        console.print("[red]Error: ls only available in cloud mode[/red]")
-        raise typer.Exit(1)
-
-    try:
-        # Get tenant info for bucket name
-        tenant_info = asyncio.run(get_mount_info())
-        bucket_name = tenant_info.bucket_name
-
-        # Get project info
-        async def _get_project():
-            async with get_client() as client:
-                response = await call_get(client, "/projects/projects")
-                projects_list = ProjectList.model_validate(response.json())
-                for proj in projects_list.projects:
-                    if generate_permalink(proj.name) == generate_permalink(name):
-                        return proj
-                return None
-
-        project_data = asyncio.run(_get_project())
-        if not project_data:
-            console.print(f"[red]Error: Project '{name}' not found[/red]")
-            raise typer.Exit(1)
-
-        # Create SyncProject (local_sync_path not needed for ls)
-        sync_project = SyncProject(
-            name=project_data.name,
-            path=normalize_project_path(project_data.path),
-        )
-
-        # List files
-        files = project_ls(sync_project, bucket_name, path=path)
-
-        if files:
-            console.print(f"\n[bold]Files in {name}" + (f"/{path}" if path else "") + ":[/bold]")
-            for file in files:
-                console.print(f"  {file}")
-            console.print(f"\n[dim]Total: {len(files)} files[/dim]")
-        else:
-            console.print(
-                f"[yellow]No files found in {name}" + (f"/{path}" if path else "") + "[/yellow]"
-            )
-
-    except Exception as e:
-        console.print(f"[red]Error: {e}[/red]")
-        raise typer.Exit(1)
-
-
@project_app.command("info")
 def display_project_info(
-    name: str = typer.Argument(..., help="Name of the project"),
    json_output: bool = typer.Option(False, "--json", help="Output in JSON format"),
 ):
    """Display detailed information and statistics about the current project."""
    try:
        # Get project info
-        info = asyncio.run(get_project_info(name))
+        info = asyncio.run(project_info.fn())  # type: ignore  # pyright: ignore [reportAttributeAccessIssue]

        if json_output:
            # Convert to JSON and print
            print(json.dumps(info.model_dump(), indent=2, default=str))
        else:
+            # Create rich display
+            console = Console()
+
            # Project configuration section
            console.print(
                Panel(
-                    f"Basic Memory version: [bold green]{info.system.version}[/bold green]\n"
                    f"[bold]Project:[/bold] {info.project_name}\n"
                    f"[bold]Path:[/bold] {info.project_path}\n"
                    f"[bold]Default Project:[/bold] {info.default_project}\n",
-                    title="Basic Memory Project Info",
+                    title="📊 Basic Memory Project Info",
                    expand=False,
                )
            )

            # Statistics section
-            stats_table = Table(title="Statistics")
+            stats_table = Table(title="📈 Statistics")
            stats_table.add_column("Metric", style="cyan")
            stats_table.add_column("Count", style="green")

@@ -806,7 +231,7 @@ def display_project_info(

            # Entity types
            if info.statistics.entity_types:
-                entity_types_table = Table(title="Entity Types")
+                entity_types_table = Table(title="📑 Entity Types")
                entity_types_table.add_column("Type", style="blue")
                entity_types_table.add_column("Count", style="green")

@@ -817,7 +242,7 @@ def display_project_info(

            # Most connected entities
            if info.statistics.most_connected_entities:  # pragma: no cover
-                connected_table = Table(title="Most Connected Entities")
+                connected_table = Table(title="🔗 Most Connected Entities")
                connected_table.add_column("Title", style="blue")
                connected_table.add_column("Permalink", style="cyan")
                connected_table.add_column("Relations", style="green")
@@ -831,7 +256,7 @@ def display_project_info(

            # Recent activity
            if info.activity.recently_updated:  # pragma: no cover
-                recent_table = Table(title="Recent Activity")
+                recent_table = Table(title="🕒 Recent Activity")
                recent_table.add_column("Title", style="blue")
                recent_table.add_column("Type", style="cyan")
                recent_table.add_column("Last Updated", style="green")
@@ -850,8 +275,44 @@ def display_project_info(

                console.print(recent_table)

+            # System status
+            system_tree = Tree("🖥️ System Status")
+            system_tree.add(f"Basic Memory version: [bold green]{info.system.version}[/bold green]")
+            system_tree.add(
+                f"Database: [cyan]{info.system.database_path}[/cyan] ([green]{info.system.database_size}[/green])"
+            )
+
+            # Watch status
+            if info.system.watch_status:  # pragma: no cover
+                watch_branch = system_tree.add("Watch Service")
+                running = info.system.watch_status.get("running", False)
+                status_color = "green" if running else "red"
+                watch_branch.add(
+                    f"Status: [bold {status_color}]{'Running' if running else 'Stopped'}[/bold {status_color}]"
+                )
+
+                if running:
+                    start_time = (
+                        datetime.fromisoformat(info.system.watch_status.get("start_time", ""))
+                        if isinstance(info.system.watch_status.get("start_time"), str)
+                        else info.system.watch_status.get("start_time")
+                    )
+                    watch_branch.add(
+                        f"Running since: [cyan]{start_time.strftime('%Y-%m-%d %H:%M')}[/cyan]"
+                    )
+                    watch_branch.add(
+                        f"Files synced: [green]{info.system.watch_status.get('synced_files', 0)}[/green]"
+                    )
+                    watch_branch.add(
+                        f"Errors: [{'red' if info.system.watch_status.get('error_count', 0) > 0 else 'green'}]{info.system.watch_status.get('error_count', 0)}[/{'red' if info.system.watch_status.get('error_count', 0) > 0 else 'green'}]"
+                    )
+            else:
+                system_tree.add("[yellow]Watch service not running[/yellow]")
+
+            console.print(system_tree)
+
            # Available projects
-            projects_table = Table(title="Available Projects")
+            projects_table = Table(title="📁 Available Projects")
            projects_table.add_column("Name", style="blue")
            projects_table.add_column("Path", style="cyan")
            projects_table.add_column("Default", style="green")
@@ -859,7 +320,7 @@ def display_project_info(
            for name, proj_info in info.available_projects.items():
                is_default = name == info.default_project
                project_path = proj_info["path"]
-                projects_table.add_row(name, project_path, "[X]" if is_default else "")
+                projects_table.add_row(name, project_path, "✓" if is_default else "")

            console.print(projects_table)

@@ -2,20 +2,19 @@

 import asyncio
 from typing import Set, Dict
-from typing import Annotated, Optional

-from mcp.server.fastmcp.exceptions import ToolError
 import typer
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
 from rich.tree import Tree

+from basic_memory import db
 from basic_memory.cli.app import app
-from basic_memory.mcp.async_client import get_client
-from basic_memory.mcp.tools.utils import call_post
-from basic_memory.schemas import SyncReportResponse
-from basic_memory.mcp.project_context import get_active_project
+from basic_memory.cli.commands.sync import get_sync_service
+from basic_memory.config import ConfigManager, get_project_config
+from basic_memory.repository import ProjectRepository
+from basic_memory.sync.sync_service import SyncReport

 # Create rich console
 console = Console()
@@ -48,7 +47,7 @@ def add_files_to_tree(
                branch.add(f"[{style}]{file_name}[/{style}]")


-def group_changes_by_directory(changes: SyncReportResponse) -> Dict[str, Dict[str, int]]:
+def group_changes_by_directory(changes: SyncReport) -> Dict[str, Dict[str, int]]:
    """Group changes by directory for summary view."""
    by_dir = {}
    for change_type, paths in [
@@ -88,13 +87,11 @@ def build_directory_summary(counts: Dict[str, int]) -> str:
    return " ".join(parts)


-def display_changes(
-    project_name: str, title: str, changes: SyncReportResponse, verbose: bool = False
-):
+def display_changes(project_name: str, title: str, changes: SyncReport, verbose: bool = False):
    """Display changes using Rich for better visualization."""
    tree = Tree(f"{project_name}: {title}")

-    if changes.total == 0 and not changes.skipped_files:
+    if changes.total == 0:
        tree.add("No changes")
        console.print(Panel(tree, expand=False))
        return
@@ -114,13 +111,6 @@ def display_changes(
        if changes.deleted:
            del_branch = tree.add("[red]Deleted[/red]")
            add_files_to_tree(del_branch, changes.deleted, "red")
-        if changes.skipped_files:
-            skip_branch = tree.add("[red]! Skipped (Circuit Breaker)[/red]")
-            for skipped in sorted(changes.skipped_files, key=lambda x: x.path):
-                skip_branch.add(
-                    f"[red]{skipped.path}[/red] "
-                    f"(failures: {skipped.failure_count}, reason: {skipped.reason})"
-                )
    else:
        # Show directory summaries
        by_dir = group_changes_by_directory(changes)
@@ -129,44 +119,36 @@ def display_changes(
            if summary:  # Only show directories with changes
                tree.add(f"[bold]{dir_name}/[/bold] {summary}")

-        # Show skipped files summary in non-verbose mode
-        if changes.skipped_files:
-            skip_count = len(changes.skipped_files)
-            tree.add(
-                f"[red]! {skip_count} file{'s' if skip_count != 1 else ''} "
-                f"skipped due to repeated failures[/red]"
-            )
-
    console.print(Panel(tree, expand=False))


-async def run_status(project: Optional[str] = None, verbose: bool = False):  # pragma: no cover
+async def run_status(verbose: bool = False):  # pragma: no cover
    """Check sync status of files vs database."""
+    # Check knowledge/ directory

-    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())
+    app_config = ConfigManager().config
+    config = get_project_config()

-            display_changes(project_item.name, "Status", sync_report, verbose)
+    _, session_maker = await db.get_or_create_db(
+        db_path=app_config.database_path, db_type=db.DatabaseType.FILESYSTEM
+    )
+    project_repository = ProjectRepository(session_maker)
+    project = await project_repository.get_by_name(config.project)
+    if not project:  # pragma: no cover
+        raise Exception(f"Project '{config.project}' not found")

-    except (ValueError, ToolError) as e:
-        console.print(f"[red]Error: {e}[/red]")
-        raise typer.Exit(1)
+    sync_service = await get_sync_service(project)
+    knowledge_changes = await sync_service.scan(config.home)
+    display_changes(project.name, "Status", knowledge_changes, verbose)


@app.command()
 def status(
-    project: Annotated[
-        Optional[str],
-        typer.Option(help="The project name."),
-    ] = None,
    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed file information"),
 ):
    """Show sync status between files and database."""
    try:
-        asyncio.run(run_status(project, verbose))  # pragma: no cover
+        asyncio.run(run_status(verbose))  # pragma: no cover
    except Exception as e:
        logger.error(f"Error checking status: {e}")
        typer.echo(f"Error checking status: {e}", err=True)
@@ -0,0 +1,242 @@
+"""Command module for basic-memory sync operations."""
+
+import asyncio
+from collections import defaultdict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Dict
+
+import typer
+from loguru import logger
+from rich.console import Console
+from rich.tree import Tree
+
+from basic_memory import db
+from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager, get_project_config
+from basic_memory.markdown import EntityParser
+from basic_memory.markdown.markdown_processor import MarkdownProcessor
+from basic_memory.models import Project
+from basic_memory.repository import (
+    EntityRepository,
+    ObservationRepository,
+    RelationRepository,
+    ProjectRepository,
+)
+from basic_memory.repository.search_repository import SearchRepository
+from basic_memory.services import EntityService, FileService
+from basic_memory.services.link_resolver import LinkResolver
+from basic_memory.services.search_service import SearchService
+from basic_memory.sync import SyncService
+from basic_memory.sync.sync_service import SyncReport
+
+console = Console()
+
+
+@dataclass
+class ValidationIssue:
+    file_path: str
+    error: str
+
+
+async def get_sync_service(project: Project) -> SyncService:  # pragma: no cover
+    """Get sync service instance with all dependencies."""
+
+    app_config = ConfigManager().config
+    _, session_maker = await db.get_or_create_db(
+        db_path=app_config.database_path, db_type=db.DatabaseType.FILESYSTEM
+    )
+
+    project_path = Path(project.path)
+    entity_parser = EntityParser(project_path)
+    markdown_processor = MarkdownProcessor(entity_parser)
+    file_service = FileService(project_path, markdown_processor)
+
+    # Initialize repositories
+    entity_repository = EntityRepository(session_maker, project_id=project.id)
+    observation_repository = ObservationRepository(session_maker, project_id=project.id)
+    relation_repository = RelationRepository(session_maker, project_id=project.id)
+    search_repository = SearchRepository(session_maker, project_id=project.id)
+
+    # Initialize services
+    search_service = SearchService(search_repository, entity_repository, file_service)
+    link_resolver = LinkResolver(entity_repository, search_service)
+
+    # Initialize services
+    entity_service = EntityService(
+        entity_parser,
+        entity_repository,
+        observation_repository,
+        relation_repository,
+        file_service,
+        link_resolver,
+    )
+
+    # Create sync service
+    sync_service = SyncService(
+        app_config=app_config,
+        entity_service=entity_service,
+        entity_parser=entity_parser,
+        entity_repository=entity_repository,
+        relation_repository=relation_repository,
+        search_service=search_service,
+        file_service=file_service,
+    )
+
+    return sync_service
+
+
+def group_issues_by_directory(issues: List[ValidationIssue]) -> Dict[str, List[ValidationIssue]]:
+    """Group validation issues by directory."""
+    grouped = defaultdict(list)
+    for issue in issues:
+        dir_name = Path(issue.file_path).parent.name
+        grouped[dir_name].append(issue)
+    return dict(grouped)
+
+
+def display_sync_summary(knowledge: SyncReport):
+    """Display a one-line summary of sync changes."""
+    config = get_project_config()
+    total_changes = knowledge.total
+    project_name = config.project
+
+    if total_changes == 0:
+        console.print(f"[green]Project '{project_name}': Everything up to date[/green]")
+        return
+
+    # Format as: "Synced X files (A new, B modified, C moved, D deleted)"
+    changes = []
+    new_count = len(knowledge.new)
+    mod_count = len(knowledge.modified)
+    move_count = len(knowledge.moves)
+    del_count = len(knowledge.deleted)
+
+    if new_count:
+        changes.append(f"[green]{new_count} new[/green]")
+    if mod_count:
+        changes.append(f"[yellow]{mod_count} modified[/yellow]")
+    if move_count:
+        changes.append(f"[blue]{move_count} moved[/blue]")
+    if del_count:
+        changes.append(f"[red]{del_count} deleted[/red]")
+
+    console.print(f"Project '{project_name}': Synced {total_changes} files ({', '.join(changes)})")
+
+
+def display_detailed_sync_results(knowledge: SyncReport):
+    """Display detailed sync results with trees."""
+    config = get_project_config()
+    project_name = config.project
+
+    if knowledge.total == 0:
+        console.print(f"\n[green]Project '{project_name}': Everything up to date[/green]")
+        return
+
+    console.print(f"\n[bold]Sync Results for Project '{project_name}'[/bold]")
+
+    if knowledge.total > 0:
+        knowledge_tree = Tree("[bold]Knowledge Files[/bold]")
+        if knowledge.new:
+            created = knowledge_tree.add("[green]Created[/green]")
+            for path in sorted(knowledge.new):
+                checksum = knowledge.checksums.get(path, "")
+                created.add(f"[green]{path}[/green] ({checksum[:8]})")
+        if knowledge.modified:
+            modified = knowledge_tree.add("[yellow]Modified[/yellow]")
+            for path in sorted(knowledge.modified):
+                checksum = knowledge.checksums.get(path, "")
+                modified.add(f"[yellow]{path}[/yellow] ({checksum[:8]})")
+        if knowledge.moves:
+            moved = knowledge_tree.add("[blue]Moved[/blue]")
+            for old_path, new_path in sorted(knowledge.moves.items()):
+                checksum = knowledge.checksums.get(new_path, "")
+                moved.add(f"[blue]{old_path}[/blue] → [blue]{new_path}[/blue] ({checksum[:8]})")
+        if knowledge.deleted:
+            deleted = knowledge_tree.add("[red]Deleted[/red]")
+            for path in sorted(knowledge.deleted):
+                deleted.add(f"[red]{path}[/red]")
+        console.print(knowledge_tree)
+
+
+async def run_sync(verbose: bool = False):
+    """Run sync operation."""
+    app_config = ConfigManager().config
+    config = get_project_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)
+    project = await project_repository.get_by_name(config.project)
+    if not project:  # pragma: no cover
+        raise Exception(f"Project '{config.project}' not found")
+
+    import time
+
+    start_time = time.time()
+
+    logger.info(
+        "Sync command started",
+        project=config.project,
+        verbose=verbose,
+        directory=str(config.home),
+    )
+
+    sync_service = await get_sync_service(project)
+
+    logger.info("Running one-time sync")
+    knowledge_changes = await sync_service.sync(config.home, project_name=project.name)
+
+    # Log results
+    duration_ms = int((time.time() - start_time) * 1000)
+    logger.info(
+        "Sync command completed",
+        project=config.project,
+        total_changes=knowledge_changes.total,
+        new_files=len(knowledge_changes.new),
+        modified_files=len(knowledge_changes.modified),
+        deleted_files=len(knowledge_changes.deleted),
+        moved_files=len(knowledge_changes.moves),
+        duration_ms=duration_ms,
+    )
+
+    # Display results
+    if verbose:
+        display_detailed_sync_results(knowledge_changes)
+    else:
+        display_sync_summary(knowledge_changes)  # pragma: no cover
+
+
+@app.command()
+def sync(
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed sync information.",
+    ),
+) -> None:
+    """Sync knowledge files with the database."""
+    config = get_project_config()
+
+    try:
+        # Show which project we're syncing
+        typer.echo(f"Syncing project: {config.project}")
+        typer.echo(f"Project path: {config.home}")
+
+        # Run sync
+        asyncio.run(run_sync(verbose=verbose))
+
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            logger.exception(
+                "Sync command failed",
+                f"project={config.project},"
+                f"error={str(e)},"
+                f"error_type={type(e).__name__},"
+                f"directory={str(config.home)}",
+            )
+            typer.echo(f"Error during sync: {e}", err=True)
+            raise typer.Exit(1)
+        raise
@@ -13,6 +13,7 @@ from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
    mcp,
    project,
    status,
+    sync,
    tool,
 )

@@ -3,13 +3,11 @@
 import json
 import os
 from dataclasses import dataclass
-from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, Literal, Optional, List, Tuple
-from enum import Enum

 from loguru import logger
-from pydantic import BaseModel, Field, field_validator
+from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict

 import basic_memory
@@ -25,13 +23,6 @@ WATCH_STATUS_JSON = "watch-status.json"
 Environment = Literal["test", "dev", "user"]


-class DatabaseBackend(str, Enum):
-    """Supported database backends."""
-
-    SQLITE = "sqlite"
-    POSTGRES = "postgres"
-
-
@dataclass
 class ProjectConfig:
    """Configuration for a specific basic-memory project."""
@@ -48,22 +39,6 @@ class ProjectConfig:
        return f"/{generate_permalink(self.name)}"


-class CloudProjectConfig(BaseModel):
-    """Sync configuration for a cloud project.
-
-    This tracks the local working directory and sync state for a project
-    that is synced with Basic Memory Cloud.
-    """
-
-    local_path: str = Field(description="Local working directory path for this cloud project")
-    last_sync: Optional[datetime] = Field(
-        default=None, description="Timestamp of last successful sync operation"
-    )
-    bisync_initialized: bool = Field(
-        default=False, description="Whether rclone bisync baseline has been established"
-    )
-
-
 class BasicMemoryConfig(BaseSettings):
    """Pydantic model for Basic Memory global configuration."""

@@ -71,10 +46,8 @@ class BasicMemoryConfig(BaseSettings):

    projects: Dict[str, str] = Field(
        default_factory=lambda: {
-            "main": str(Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory")))
-        }
-        if os.getenv("BASIC_MEMORY_HOME")
-        else {},
+            "main": Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory")).as_posix()
+        },
        description="Mapping of project names to their filesystem paths",
    )
    default_project: str = Field(
@@ -89,17 +62,6 @@ class BasicMemoryConfig(BaseSettings):
    # overridden by ~/.basic-memory/config.json
    log_level: str = "INFO"

-    # Database configuration
-    database_backend: DatabaseBackend = Field(
-        default=DatabaseBackend.SQLITE,
-        description="Database backend to use (sqlite or postgres)",
-    )
-
-    database_url: Optional[str] = Field(
-        default=None,
-        description="Database connection URL. For Postgres, use postgresql+asyncpg://user:pass@host:port/db. If not set, SQLite will use default path.",
-    )
-
    # Watch service configuration
    sync_delay: int = Field(
        default=1000, description="Milliseconds to wait after changes before syncing", gt=0
@@ -120,48 +82,20 @@ class BasicMemoryConfig(BaseSettings):
        description="Whether to sync changes in real time. default (True)",
    )

-    sync_thread_pool_size: int = Field(
-        default=4,
-        description="Size of thread pool for file I/O operations in sync service. Default of 4 is optimized for cloud deployments with 1-2GB RAM.",
-        gt=0,
-    )
-
-    sync_max_concurrent_files: int = Field(
-        default=10,
-        description="Maximum number of files to process concurrently during sync. Limits memory usage on large projects (2000+ files). Lower values reduce memory consumption.",
-        gt=0,
-    )
-
-    sync_batch_size: int = Field(
-        default=100,
-        description="Number of files to process in a single database transaction during sync. Higher values improve performance with remote databases (Postgres) but increase memory usage. Typical values: 100 (conservative), 500 (balanced), 1000 (aggressive).",
-        gt=0,
-    )
-
    kebab_filenames: bool = Field(
        default=False,
        description="Format for generated filenames. False preserves spaces and special chars, True converts them to hyphens for consistency with permalinks",
    )

-    disable_permalinks: bool = Field(
-        default=False,
-        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.",
-    )
-
-    skip_initialization_sync: bool = Field(
-        default=False,
-        description="Skip expensive initialization synchronization. Useful for cloud/stateless deployments where project reconciliation is not needed.",
-    )
-
-    # Project path constraints
-    project_root: Optional[str] = Field(
+    # API connection configuration
+    api_url: Optional[str] = Field(
        default=None,
-        description="If set, all projects must be created underneath this directory. Paths will be sanitized and constrained to this root. If not set, projects can be created anywhere (default behavior).",
+        description="URL of remote Basic Memory API. If set, MCP will connect to this API instead of using local ASGI transport.",
    )

    # Cloud configuration
    cloud_client_id: str = Field(
-        default="client_01K6KWQPW6J1M8VV7R3TZP5A6M",
+        default="client_01K4DGBWAZWP83N3H8VVEMRX6W",
        description="OAuth client ID for Basic Memory Cloud",
    )

@@ -171,41 +105,15 @@ class BasicMemoryConfig(BaseSettings):
    )

    cloud_host: str = Field(
-        default_factory=lambda: os.getenv(
-            "BASIC_MEMORY_CLOUD_HOST", "https://cloud.basicmemory.com"
-        ),
-        description="Basic Memory Cloud host URL",
+        default="https://cloud.basicmemory.com",
+        description="Basic Memory Cloud proxy host URL",
    )

-    cloud_mode: bool = Field(
-        default=False,
-        description="Enable cloud mode - all requests go to cloud instead of local (config file value)",
-    )
-
-    cloud_projects: Dict[str, CloudProjectConfig] = Field(
-        default_factory=dict,
-        description="Cloud project sync configuration mapping project names to their local paths and sync state",
-    )
-
-    @property
-    def cloud_mode_enabled(self) -> bool:
-        """Check if cloud mode is enabled.
-
-        Priority:
-        1. BASIC_MEMORY_CLOUD_MODE environment variable
-        2. Config file value (cloud_mode)
-        """
-        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
-
    model_config = SettingsConfigDict(
        env_prefix="BASIC_MEMORY_",
        extra="ignore",
+        env_file=".env",
+        env_file_encoding="utf-8",
    )

    def get_project_path(self, project_name: Optional[str] = None) -> Path:  # pragma: no cover
@@ -219,16 +127,15 @@ class BasicMemoryConfig(BaseSettings):

    def model_post_init(self, __context: Any) -> None:
        """Ensure configuration is valid after initialization."""
-        # Ensure at least one project exists; if none exist then create main
-        if not self.projects:  # pragma: no cover
-            self.projects["main"] = str(
+        # Ensure main project exists
+        if "main" not in self.projects:  # pragma: no cover
+            self.projects["main"] = (
                Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory"))
-            )
+            ).as_posix()

-        # Ensure default project is valid (i.e. points to an existing project)
+        # Ensure default project is valid
        if self.default_project not in self.projects:  # pragma: no cover
-            # Set default to first available project
-            self.default_project = next(iter(self.projects.keys()))
+            self.default_project = "main"

    @property
    def app_database_path(self) -> Path:
@@ -280,10 +187,6 @@ class BasicMemoryConfig(BaseSettings):
        return Path.home() / DATA_DIR_NAME


-# Module-level cache for configuration
-_CONFIG_CACHE: Optional[BasicMemoryConfig] = None
-
-
 class ConfigManager:
    """Manages Basic Memory configuration."""

@@ -293,12 +196,7 @@ class ConfigManager:
        if isinstance(home, str):
            home = Path(home)

-        # Allow override via environment variable
-        if config_dir := os.getenv("BASIC_MEMORY_CONFIG_DIR"):
-            self.config_dir = Path(config_dir)
-        else:
-            self.config_dir = home / DATA_DIR_NAME
-
+        self.config_dir = home / DATA_DIR_NAME
        self.config_file = self.config_dir / CONFIG_FILE_NAME

        # Ensure config directory exists
@@ -310,45 +208,12 @@ class ConfigManager:
        return self.load_config()

    def load_config(self) -> BasicMemoryConfig:
-        """Load configuration from file or create default.
-
-        Environment variables take precedence over file config values,
-        following Pydantic Settings best practices.
-
-        Uses module-level cache for performance across ConfigManager instances.
-        """
-        global _CONFIG_CACHE
-
-        # Return cached config if available
-        if _CONFIG_CACHE is not None:
-            return _CONFIG_CACHE
+        """Load configuration from file or create default."""

        if self.config_file.exists():
            try:
-                file_data = json.loads(self.config_file.read_text(encoding="utf-8"))
-
-                # First, create config from environment variables (Pydantic will read them)
-                # Then overlay with file data for fields that aren't set via env vars
-                # This ensures env vars take precedence
-
-                # Get env-based config fields that are actually set
-                env_config = BasicMemoryConfig()
-                env_dict = env_config.model_dump()
-
-                # Merge: file data as base, but only use it for fields not set by env
-                # We detect env-set fields by comparing to default values
-                merged_data = file_data.copy()
-
-                # For fields that have env var overrides, use those instead of file values
-                # The env_prefix is "BASIC_MEMORY_" so we check those
-                for field_name in BasicMemoryConfig.model_fields.keys():
-                    env_var_name = f"BASIC_MEMORY_{field_name.upper()}"
-                    if env_var_name in os.environ:
-                        # Environment variable is set, use it
-                        merged_data[field_name] = env_dict[field_name]
-
-                _CONFIG_CACHE = BasicMemoryConfig(**merged_data)
-                return _CONFIG_CACHE
+                data = json.loads(self.config_file.read_text(encoding="utf-8"))
+                return BasicMemoryConfig(**data)
            except Exception as e:  # pragma: no cover
                logger.exception(f"Failed to load config: {e}")
                raise e
@@ -358,11 +223,8 @@ class ConfigManager:
            return config

    def save_config(self, config: BasicMemoryConfig) -> None:
-        """Save configuration to file and invalidate cache."""
-        global _CONFIG_CACHE
+        """Save configuration to file."""
        save_basic_memory_config(self.config_file, config)
-        # Invalidate cache so next load_config() reads fresh data
-        _CONFIG_CACHE = None

    @property
    def projects(self) -> Dict[str, str]:
@@ -386,7 +248,7 @@ class ConfigManager:

        # Load config, modify it, and save it
        config = self.load_config()
-        config.projects[name] = str(project_path)
+        config.projects[name] = project_path.as_posix()
        self.save_config(config)
        return ProjectConfig(name=name, home=project_path)

@@ -402,8 +264,7 @@ class ConfigManager:
        if project_name == config.default_project:  # pragma: no cover
            raise ValueError(f"Cannot remove the default project '{name}'")

-        # Use the found project_name (which may differ from input name due to permalink matching)
-        del config.projects[project_name]
+        del config.projects[name]
        self.save_config(config)

    def set_default_project(self, name: str) -> None:
@@ -443,7 +304,7 @@ def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
    os_project_name = os.environ.get("BASIC_MEMORY_PROJECT", None)
    if os_project_name:  # pragma: no cover
        logger.warning(
-            f"BASIC_MEMORY_PROJECT is not supported anymore. Set the default project in the config instead. Setting default project to {os_project_name}"
+            f"BASIC_MEMORY_PROJECT is not supported anymore. Use the --project flag or set the default project in the config instead. Setting default project to {os_project_name}"
        )
        actual_project_name = project_name
    # if the project_name is passed in, use it
@@ -469,13 +330,20 @@ def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
 def save_basic_memory_config(file_path: Path, config: BasicMemoryConfig) -> None:
    """Save configuration to file."""
    try:
-        # Use model_dump with mode='json' to serialize datetime objects properly
-        config_dict = config.model_dump(mode="json")
-        file_path.write_text(json.dumps(config_dict, indent=2))
+        file_path.write_text(json.dumps(config.model_dump(), indent=2))
    except Exception as e:  # pragma: no cover
        logger.error(f"Failed to save config: {e}")


+def update_current_project(project_name: str) -> None:
+    """Update the global config to use a different project.
+
+    This is used by the CLI when --project flag is specified.
+    """
+    global config
+    config = get_project_config(project_name)  # pragma: no cover
+
+
 # setup logging to a single log file in user home directory
 user_home = Path.home()
 log_dir = user_home / DATA_DIR_NAME
@@ -1,16 +1,15 @@
 import asyncio
-import os
 from contextlib import asynccontextmanager
 from enum import Enum, auto
 from pathlib import Path
 from typing import AsyncGenerator, Optional

-from basic_memory.config import BasicMemoryConfig, ConfigManager, DatabaseBackend
+from basic_memory.config import BasicMemoryConfig, ConfigManager
 from alembic import command
 from alembic.config import Config

 from loguru import logger
-from sqlalchemy import text, event
+from sqlalchemy import text
 from sqlalchemy.ext.asyncio import (
    create_async_engine,
    async_sessionmaker,
@@ -18,14 +17,13 @@ from sqlalchemy.ext.asyncio import (
    AsyncEngine,
    async_scoped_session,
 )
-from sqlalchemy.pool import NullPool

-from basic_memory.repository.postgres_search_repository import PostgresSearchRepository
-from basic_memory.repository.sqlite_search_repository import SQLiteSearchRepository
+from basic_memory.repository.search_repository import SearchRepository

 # Module level state
 _engine: Optional[AsyncEngine] = None
 _session_maker: Optional[async_sessionmaker[AsyncSession]] = None
+_migrations_completed: bool = False


 class DatabaseType(Enum):
@@ -35,33 +33,8 @@ class DatabaseType(Enum):
    FILESYSTEM = auto()

    @classmethod
-    def get_db_url(
-        cls, db_path: Path, db_type: "DatabaseType", config: Optional[BasicMemoryConfig] = None
-    ) -> str:
-        """Get SQLAlchemy URL for database path.
-
-        Args:
-            db_path: Path to SQLite database file (ignored for Postgres)
-            db_type: Type of database (MEMORY or FILESYSTEM)
-            config: Optional config to check for database backend and URL
-
-        Returns:
-            SQLAlchemy connection URL
-        """
-        # Load config if not provided
-        if config is None:
-            config = ConfigManager().config
-
-        # Check if Postgres backend is configured
-        if config.database_backend == DatabaseBackend.POSTGRES:
-            if not config.database_url:
-                raise ValueError("DATABASE_URL must be set when using Postgres backend")
-            logger.info(
-                f"Using Postgres database: {config.database_url.split('@')[1] if '@' in config.database_url else config.database_url}"
-            )
-            return config.database_url
-
-        # Default to SQLite
+    def get_db_url(cls, db_path: Path, db_type: "DatabaseType") -> str:
+        """Get SQLAlchemy URL for database path."""
        if db_type == cls.MEMORY:
            logger.info("Using in-memory SQLite database")
            return "sqlite+aiosqlite://"
@@ -89,14 +62,7 @@ async def scoped_session(
    factory = get_scoped_session_factory(session_maker)
    session = factory()
    try:
-        # Only enable foreign keys for SQLite (Postgres has them enabled by default)
-        # Detect database type from session's bind (engine) dialect
-        engine = session.get_bind()
-        dialect_name = engine.dialect.name
-
-        if dialect_name == "sqlite":
-            await session.execute(text("PRAGMA foreign_keys=ON"))
-
+        await session.execute(text("PRAGMA foreign_keys=ON"))
        yield session
        await session.commit()
    except Exception:
@@ -107,124 +73,13 @@ async def scoped_session(
        await factory.remove()


-def _configure_sqlite_connection(dbapi_conn, enable_wal: bool = True) -> None:
-    """Configure SQLite connection with WAL mode and optimizations.
-
-    Args:
-        dbapi_conn: Database API connection object
-        enable_wal: Whether to enable WAL mode (should be False for in-memory databases)
-    """
-    cursor = dbapi_conn.cursor()
-    try:
-        # Enable WAL mode for better concurrency (not supported for in-memory databases)
-        if enable_wal:
-            cursor.execute("PRAGMA journal_mode=WAL")
-        # Set busy timeout to handle locked databases
-        cursor.execute("PRAGMA busy_timeout=10000")  # 10 seconds
-        # Optimize for performance
-        cursor.execute("PRAGMA synchronous=NORMAL")
-        cursor.execute("PRAGMA cache_size=-64000")  # 64MB cache
-        cursor.execute("PRAGMA temp_store=MEMORY")
-        # Windows-specific optimizations
-        if os.name == "nt":
-            cursor.execute("PRAGMA locking_mode=NORMAL")  # Ensure normal locking on Windows
-    except Exception as e:
-        # Log but don't fail - some PRAGMAs may not be supported
-        logger.warning(f"Failed to configure SQLite connection: {e}")
-    finally:
-        cursor.close()
-
-
-def _create_sqlite_engine(db_url: str, db_type: DatabaseType) -> AsyncEngine:
-    """Create SQLite async engine with appropriate configuration.
-
-    Args:
-        db_url: SQLite connection URL
-        db_type: Database type (MEMORY or FILESYSTEM)
-
-    Returns:
-        Configured async engine for SQLite
-    """
-    # Configure connection args with Windows-specific settings
-    connect_args: dict[str, bool | float | None] = {"check_same_thread": False}
-
-    # Add Windows-specific parameters to improve reliability
-    if os.name == "nt":  # Windows
-        connect_args.update(
-            {
-                "timeout": 30.0,  # Increase timeout to 30 seconds for Windows
-                "isolation_level": None,  # Use autocommit mode
-            }
-        )
-        # Use NullPool for Windows filesystem databases to avoid connection pooling issues
-        # Important: Do NOT use NullPool for in-memory databases as it will destroy the database
-        # between connections
-        if db_type == DatabaseType.FILESYSTEM:
-            engine = create_async_engine(
-                db_url,
-                connect_args=connect_args,
-                poolclass=NullPool,  # Disable connection pooling on Windows
-                echo=False,
-            )
-        else:
-            # In-memory databases need connection pooling to maintain state
-            engine = create_async_engine(db_url, connect_args=connect_args)
-    else:
-        engine = create_async_engine(db_url, connect_args=connect_args)
-
-    # Enable WAL mode for better concurrency and reliability
-    # Note: WAL mode is not supported for in-memory databases
-    enable_wal = db_type != DatabaseType.MEMORY
-
-    @event.listens_for(engine.sync_engine, "connect")
-    def enable_wal_mode(dbapi_conn, connection_record):
-        """Enable WAL mode on each connection."""
-        _configure_sqlite_connection(dbapi_conn, enable_wal=enable_wal)
-
-    return engine
-
-
-def _create_postgres_engine(db_url: str) -> AsyncEngine:
-    """Create Postgres async engine with appropriate configuration.
-
-    Args:
-        db_url: Postgres connection URL (postgresql+asyncpg://...)
-
-    Returns:
-        Configured async engine for Postgres
-    """
-    # Postgres with asyncpg - use standard async connection
-    engine = create_async_engine(
-        db_url,
-        echo=False,
-        pool_pre_ping=True,  # Verify connections before using them
-    )
-
-    return engine
-
-
 def _create_engine_and_session(
    db_path: Path, db_type: DatabaseType = DatabaseType.FILESYSTEM
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
-    """Internal helper to create engine and session maker.
-
-    Args:
-        db_path: Path to database file (used for SQLite, ignored for Postgres)
-        db_type: Type of database (MEMORY or FILESYSTEM)
-
-    Returns:
-        Tuple of (engine, session_maker)
-    """
-    config = ConfigManager().config
-    db_url = DatabaseType.get_db_url(db_path, db_type, config)
+    """Internal helper to create engine and session maker."""
+    db_url = DatabaseType.get_db_url(db_path, db_type)
    logger.debug(f"Creating engine for db_url: {db_url}")
-
-    # Delegate to backend-specific engine creation
-    if config.database_backend == DatabaseBackend.POSTGRES:
-        engine = _create_postgres_engine(db_url)
-    else:
-        engine = _create_sqlite_engine(db_url, db_type)
-
+    engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
    session_maker = async_sessionmaker(engine, expire_on_commit=False)
    return engine, session_maker

@@ -260,12 +115,13 @@ async def get_or_create_db(

 async def shutdown_db() -> None:  # pragma: no cover
    """Clean up database connections."""
-    global _engine, _session_maker
+    global _engine, _session_maker, _migrations_completed

    if _engine:
        await _engine.dispose()
        _engine = None
        _session_maker = None
+        _migrations_completed = False


@asynccontextmanager
@@ -279,12 +135,15 @@ async def engine_session_factory(
    for each test. For production use, use get_or_create_db() instead.
    """

-    global _engine, _session_maker
+    global _engine, _session_maker, _migrations_completed

-    # Use the same helper function as production code
-    _engine, _session_maker = _create_engine_and_session(db_path, db_type)
+    db_url = DatabaseType.get_db_url(db_path, db_type)
+    logger.debug(f"Creating engine for db_url: {db_url}")

+    _engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
    try:
+        _session_maker = async_sessionmaker(_engine, expire_on_commit=False)
+
        # Verify that engine and session maker are initialized
        if _engine is None:  # pragma: no cover
            logger.error("Database engine is None in engine_session_factory")
@@ -300,16 +159,20 @@ async def engine_session_factory(
            await _engine.dispose()
            _engine = None
            _session_maker = None
+            _migrations_completed = False


 async def run_migrations(
-    app_config: BasicMemoryConfig, database_type=DatabaseType.FILESYSTEM
+    app_config: BasicMemoryConfig, database_type=DatabaseType.FILESYSTEM, force: bool = False
 ):  # pragma: no cover
-    """Run any pending alembic migrations.
+    """Run any pending alembic migrations."""
+    global _migrations_completed
+
+    # Skip if migrations already completed unless forced
+    if _migrations_completed and not force:
+        logger.debug("Migrations already completed in this session, skipping")
+        return

-    Note: Alembic tracks which migrations have been applied via the alembic_version table,
-    so it's safe to call this multiple times - it will only run pending migrations.
-    """
    logger.info("Running database migrations...")
    try:
        # Get the absolute path to the alembic directory relative to this file
@@ -324,16 +187,9 @@ async def run_migrations(
        )
        config.set_main_option("timezone", "UTC")
        config.set_main_option("revision_environment", "false")
-
-        # Get the correct database URL based on backend configuration
-        db_url = DatabaseType.get_db_url(app_config.database_path, database_type, app_config)
-
-        # For Postgres, Alembic needs synchronous driver (psycopg2), not async (asyncpg)
-        if app_config.database_backend == DatabaseBackend.POSTGRES:
-            # Convert asyncpg URL to psycopg2 URL for Alembic
-            db_url = db_url.replace("postgresql+asyncpg://", "postgresql://")
-
-        config.set_main_option("sqlalchemy.url", db_url)
+        config.set_main_option(
+            "sqlalchemy.url", DatabaseType.get_db_url(app_config.database_path, database_type)
+        )

        command.upgrade(config, "head")
        logger.info("Migrations completed successfully")
@@ -344,14 +200,12 @@ async def run_migrations(
        else:
            session_maker = _session_maker

-        # Initialize the search index schema
-        # For SQLite: Create FTS5 virtual table
-        # For Postgres: No-op (tsvector column added by migrations)
-        # The project_id is not used for init_search_index, so we pass a dummy value
-        if app_config.database_backend == DatabaseBackend.POSTGRES:
-            await PostgresSearchRepository(session_maker, 1).init_search_index()
-        else:
-            await SQLiteSearchRepository(session_maker, 1).init_search_index()
+        # initialize the search Index schema
+        # the project_id is not used for init_search_index, so we pass a dummy value
+        await SearchRepository(session_maker, 1).init_search_index()
+
+        # Mark migrations as completed
+        _migrations_completed = True
    except Exception as e:  # pragma: no cover
        logger.error(f"Error running migrations: {e}")
        raise
@@ -3,7 +3,7 @@
 from typing import Annotated
 from loguru import logger

-from fastapi import Depends, HTTPException, Path, status, Request
+from fastapi import Depends, HTTPException, Path, status
 from sqlalchemy.ext.asyncio import (
    AsyncSession,
    AsyncEngine,
@@ -25,7 +25,7 @@ from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.repository.observation_repository import ObservationRepository
 from basic_memory.repository.project_repository import ProjectRepository
 from basic_memory.repository.relation_repository import RelationRepository
-from basic_memory.repository.search_repository import SearchRepository, create_search_repository
+from basic_memory.repository.search_repository import SearchRepository
 from basic_memory.services import EntityService, ProjectService
 from basic_memory.services.context_service import ContextService
 from basic_memory.services.directory_service import DirectoryService
@@ -33,7 +33,6 @@ from basic_memory.services.file_service import FileService
 from basic_memory.services.link_resolver import LinkResolver
 from basic_memory.services.search_service import SearchService
 from basic_memory.sync import SyncService
-from basic_memory.utils import generate_permalink


 def get_app_config() -> BasicMemoryConfig:  # pragma: no cover
@@ -62,9 +61,8 @@ async def get_project_config(
    Raises:
        HTTPException: If project is not found
    """
-    # Convert project name to permalink for lookup
-    project_permalink = generate_permalink(str(project))
-    project_obj = await project_repository.get_by_permalink(project_permalink)
+
+    project_obj = await project_repository.get_by_permalink(str(project))
    if project_obj:
        return ProjectConfig(name=project_obj.name, home=pathlib.Path(project_obj.path))

@@ -80,24 +78,9 @@ ProjectConfigDep = Annotated[ProjectConfig, Depends(get_project_config)]  # prag


 async def get_engine_factory(
-    request: Request,
+    app_config: AppConfigDep,
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:  # pragma: no cover
-    """Get cached engine and session maker from app state.
-
-    For API requests, returns cached connections from app.state for optimal performance.
-    For non-API contexts (CLI), falls back to direct database connection.
-    """
-    # Try to get cached connections from app state (API context)
-    if (
-        hasattr(request, "app")
-        and hasattr(request.app.state, "engine")
-        and hasattr(request.app.state, "session_maker")
-    ):
-        return request.app.state.engine, request.app.state.session_maker
-
-    # Fallback for non-API contexts (CLI)
-    logger.debug("Using fallback database connection for non-API context")
-    app_config = get_app_config()
+    """Get engine and session maker."""
    engine, session_maker = await db.get_or_create_db(app_config.database_path)
    return engine, session_maker

@@ -149,9 +132,9 @@ async def get_project_id(
    Raises:
        HTTPException: If project is not found
    """
-    # Convert project name to permalink for lookup
-    project_permalink = generate_permalink(str(project))
-    project_obj = await project_repository.get_by_permalink(project_permalink)
+
+    # Try by permalink first (most common case with URL paths)
+    project_obj = await project_repository.get_by_permalink(str(project))
    if project_obj:
        return project_obj.id

@@ -214,12 +197,8 @@ async def get_search_repository(
    session_maker: SessionMakerDep,
    project_id: ProjectIdDep,
 ) -> 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)
+    """Create a SearchRepository instance for the current project."""
+    return SearchRepository(session_maker, project_id=project_id)


 SearchRepositoryDep = Annotated[SearchRepository, Depends(get_search_repository)]
@@ -266,7 +245,6 @@ async def get_entity_service(
    entity_parser: EntityParserDep,
    file_service: FileServiceDep,
    link_resolver: "LinkResolverDep",
-    app_config: AppConfigDep,
 ) -> EntityService:
    """Create EntityService with repository."""
    return EntityService(
@@ -276,7 +254,6 @@ async def get_entity_service(
        entity_parser=entity_parser,
        file_service=file_service,
        link_resolver=link_resolver,
-        app_config=app_config,
    )


@@ -325,7 +302,6 @@ async def get_sync_service(
    entity_parser: EntityParserDep,
    entity_repository: EntityRepositoryDep,
    relation_repository: RelationRepositoryDep,
-    project_repository: ProjectRepositoryDep,
    search_service: SearchServiceDep,
    file_service: FileServiceDep,
 ) -> SyncService:  # pragma: no cover
@@ -339,7 +315,6 @@ async def get_sync_service(
        entity_parser=entity_parser,
        entity_repository=entity_repository,
        relation_repository=relation_repository,
-        project_repository=project_repository,
        search_service=search_service,
        file_service=file_service,
    )
@@ -5,7 +5,6 @@ from pathlib import Path
 import re
 from typing import Any, Dict, Union

-import aiofiles
 import yaml
 import frontmatter
 from loguru import logger
@@ -53,12 +52,29 @@ async def compute_checksum(content: Union[str, bytes]) -> str:
        raise FileError(f"Failed to compute checksum: {e}")


+async def ensure_directory(path: FilePath) -> None:
+    """
+    Ensure directory exists, creating if necessary.
+
+    Args:
+        path: Directory path to ensure (Path or string)
+
+    Raises:
+        FileWriteError: If directory creation fails
+    """
+    try:
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        path_obj.mkdir(parents=True, exist_ok=True)
+    except Exception as e:  # pragma: no cover
+        logger.error("Failed to create directory", path=str(path), error=str(e))
+        raise FileWriteError(f"Failed to create directory {path}: {e}")
+
+
 async def write_file_atomic(path: FilePath, content: str) -> None:
    """
    Write file with atomic operation using temporary file.

-    Uses aiofiles for true async I/O (non-blocking).
-
    Args:
        path: Target file path (Path or string)
        content: Content to write
@@ -71,11 +87,7 @@ async def write_file_atomic(path: FilePath, content: str) -> None:
    temp_path = path_obj.with_suffix(".tmp")

    try:
-        # Use aiofiles for non-blocking write
-        async with aiofiles.open(temp_path, mode="w", encoding="utf-8") as f:
-            await f.write(content)
-
-        # Atomic rename (this is fast, doesn't need async)
+        temp_path.write_text(content, encoding="utf-8")
        temp_path.replace(path_obj)
        logger.debug("Wrote file atomically", path=str(path_obj), content_length=len(content))
    except Exception as e:  # pragma: no cover
@@ -173,26 +185,74 @@ def remove_frontmatter(content: str) -> str:
    return parts[2].strip()


+async def update_frontmatter(path: FilePath, updates: Dict[str, Any]) -> str:
+    """Update frontmatter fields in a file while preserving all content.
+
+    Only modifies the frontmatter section, leaving all content untouched.
+    Creates frontmatter section if none exists.
+    Returns checksum of updated file.
+
+    Args:
+        path: Path to markdown file (Path or string)
+        updates: Dict of frontmatter fields to update
+
+    Returns:
+        Checksum of updated file
+
+    Raises:
+        FileError: If file operations fail
+        ParseError: If frontmatter parsing fails
+    """
+    try:
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+
+        # Read current content
+        content = path_obj.read_text(encoding="utf-8")
+
+        # Parse current frontmatter
+        current_fm = {}
+        if has_frontmatter(content):
+            current_fm = parse_frontmatter(content)
+            content = remove_frontmatter(content)
+
+        # Update frontmatter
+        new_fm = {**current_fm, **updates}
+
+        # Write new file with updated frontmatter
+        yaml_fm = yaml.dump(new_fm, sort_keys=False, allow_unicode=True)
+        final_content = f"---\n{yaml_fm}---\n\n{content.strip()}"
+
+        logger.debug("Updating frontmatter", path=str(path_obj), update_keys=list(updates.keys()))
+
+        await write_file_atomic(path_obj, final_content)
+        return await compute_checksum(final_content)
+
+    except Exception as e:  # pragma: no cover
+        logger.error(
+            "Failed to update frontmatter",
+            path=str(path) if isinstance(path, (str, Path)) else "<unknown>",
+            error=str(e),
+        )
+        raise FileError(f"Failed to update frontmatter: {e}")
+
+
 def dump_frontmatter(post: frontmatter.Post) -> str:
    """
    Serialize frontmatter.Post to markdown with Obsidian-compatible YAML format.

-    This function ensures that:
-    1. Tags are formatted as YAML lists instead of JSON arrays
-    2. String values are properly quoted to handle special characters (colons, etc.)
+    This function ensures that tags are formatted as YAML lists instead of JSON arrays:

    Good (Obsidian compatible):
    ---
-    title: "L2 Governance Core (Split: Core)"
    tags:
    - system
    - overview
    - reference
    ---

-    Bad (causes parsing errors):
+    Bad (current behavior):
    ---
-    title: L2 Governance Core (Split: Core)  # Unquoted colon breaks YAML
    tags: ["system", "overview", "reference"]
    ---

@@ -207,13 +267,8 @@ def dump_frontmatter(post: frontmatter.Post) -> str:
        return post.content

    # Serialize YAML with block style for lists
-    # SafeDumper automatically quotes values with special characters (colons, etc.)
    yaml_str = yaml.dump(
-        post.metadata,
-        sort_keys=False,
-        allow_unicode=True,
-        default_flow_style=False,
-        Dumper=yaml.SafeDumper,
+        post.metadata, sort_keys=False, allow_unicode=True, default_flow_style=False
    )

    # Construct the final markdown with frontmatter
@@ -6,202 +6,58 @@ from typing import Set


 # Common directories and patterns to ignore by default
-# These are used as fallback if .bmignore doesn't exist
 DEFAULT_IGNORE_PATTERNS = {
-    # Hidden files (files starting with dot)
-    ".*",
-    # Basic Memory internal files
-    "*.db",
-    "*.db-shm",
-    "*.db-wal",
-    "config.json",
-    # Version control
    ".git",
-    ".svn",
-    # Python
-    "__pycache__",
-    "*.pyc",
-    "*.pyo",
-    "*.pyd",
-    ".pytest_cache",
-    ".coverage",
-    "*.egg-info",
-    ".tox",
-    ".mypy_cache",
-    ".ruff_cache",
-    # Virtual environments
    ".venv",
    "venv",
    "env",
    ".env",
-    # Node.js
    "node_modules",
-    # Build artifacts
-    "build",
-    "dist",
-    ".cache",
-    # IDE
-    ".idea",
-    ".vscode",
-    # OS files
+    "__pycache__",
+    ".pytest_cache",
+    ".coverage",
+    "*.pyc",
+    "*.pyo",
+    "*.pyd",
    ".DS_Store",
    "Thumbs.db",
-    "desktop.ini",
-    # Obsidian
+    ".idea",
+    ".vscode",
+    "*.egg-info",
+    "build",
+    "dist",
+    ".tox",
+    ".cache",
+    ".mypy_cache",
+    ".ruff_cache",
    ".obsidian",
-    # Temporary files
-    "*.tmp",
-    "*.swp",
-    "*.swo",
-    "*~",
+    ".idea",
 }


-def get_bmignore_path() -> Path:
-    """Get path to .bmignore file.
-
-    Returns:
-        Path to ~/.basic-memory/.bmignore
-    """
-    return Path.home() / ".basic-memory" / ".bmignore"
-
-
-def create_default_bmignore() -> None:
-    """Create default .bmignore file if it doesn't exist.
-
-    This ensures users have a file they can customize for all Basic Memory operations.
-    """
-    bmignore_path = get_bmignore_path()
-
-    if bmignore_path.exists():
-        return
-
-    bmignore_path.parent.mkdir(parents=True, exist_ok=True)
-    bmignore_path.write_text("""# Basic Memory Ignore Patterns
-# This file is used by both 'bm cloud upload', 'bm cloud bisync', and file sync
-# Patterns use standard gitignore-style syntax
-
-# Hidden files (files starting with dot)
-.*
-
-# Basic Memory internal files (includes test databases)
-*.db
-*.db-shm
-*.db-wal
-config.json
-
-# Version control
-.git
-.svn
-
-# Python
-__pycache__
-*.pyc
-*.pyo
-*.pyd
-.pytest_cache
-.coverage
-*.egg-info
-.tox
-.mypy_cache
-.ruff_cache
-
-# Virtual environments
-.venv
-venv
-env
-.env
-
-# Node.js
-node_modules
-
-# Build artifacts
-build
-dist
-.cache
-
-# IDE
-.idea
-.vscode
-
-# OS files
-.DS_Store
-Thumbs.db
-desktop.ini
-
-# Obsidian
-.obsidian
-
-# Temporary files
-*.tmp
-*.swp
-*.swo
-*~
-""")
-
-
-def load_bmignore_patterns() -> Set[str]:
-    """Load patterns from .bmignore file.
-
-    Returns:
-        Set of patterns from .bmignore, or DEFAULT_IGNORE_PATTERNS if file doesn't exist
-    """
-    bmignore_path = get_bmignore_path()
-
-    # Create default file if it doesn't exist
-    if not bmignore_path.exists():
-        create_default_bmignore()
-
-    patterns = set()
-
-    try:
-        with bmignore_path.open("r", encoding="utf-8") as f:
-            for line in f:
-                line = line.strip()
-                # Skip empty lines and comments
-                if line and not line.startswith("#"):
-                    patterns.add(line)
-    except Exception:
-        # If we can't read .bmignore, fall back to defaults
-        return set(DEFAULT_IGNORE_PATTERNS)
-
-    # If no patterns were loaded, use defaults
-    if not patterns:
-        return set(DEFAULT_IGNORE_PATTERNS)
-
-    return patterns
-
-
-def load_gitignore_patterns(base_path: Path, use_gitignore: bool = True) -> Set[str]:
-    """Load gitignore patterns from .gitignore file and .bmignore.
-
-    Combines patterns from:
-    1. ~/.basic-memory/.bmignore (user's global ignore patterns)
-    2. {base_path}/.gitignore (project-specific patterns, if use_gitignore=True)
+def load_gitignore_patterns(base_path: Path) -> Set[str]:
+    """Load gitignore patterns from .gitignore file and add default patterns.

    Args:
        base_path: The base directory to search for .gitignore file
-        use_gitignore: If False, only load patterns from .bmignore (default: True)

    Returns:
        Set of patterns to ignore
    """
-    # Start with patterns from .bmignore
-    patterns = load_bmignore_patterns()
+    patterns = set(DEFAULT_IGNORE_PATTERNS)

-    if use_gitignore:
-        gitignore_file = base_path / ".gitignore"
-        if gitignore_file.exists():
-            try:
-                with gitignore_file.open("r", encoding="utf-8") as f:
-                    for line in f:
-                        line = line.strip()
-                        # Skip empty lines and comments
-                        if line and not line.startswith("#"):
-                            patterns.add(line)
-            except Exception:
-                # If we can't read .gitignore, just use default patterns
-                pass
+    gitignore_file = base_path / ".gitignore"
+    if gitignore_file.exists():
+        try:
+            with gitignore_file.open("r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    # Skip empty lines and comments
+                    if line and not line.startswith("#"):
+                        patterns.add(line)
+        except Exception:
+            # If we can't read .gitignore, just use default patterns
+            pass

    return patterns

@@ -253,13 +109,7 @@ def should_ignore_path(file_path: Path, base_path: Path, ignore_patterns: Set[st
            if pattern in relative_path.parts:
                return True

-            # Check if any individual path part matches the glob pattern
-            # This handles cases like ".*" matching ".hidden.md" in "concept/.hidden.md"
-            for part in relative_path.parts:
-                if fnmatch.fnmatch(part, pattern):
-                    return True
-
-            # Glob pattern match on full path
+            # Glob pattern match
            if fnmatch.fnmatch(relative_posix, pattern) or fnmatch.fnmatch(relative_str, pattern):
                return True

@@ -153,12 +153,7 @@ class ClaudeConversationsImporter(Importer[ChatImportResult]):
            # Handle message content
            content = msg.get("text", "")
            if msg.get("content"):
-                # Filter out None values before joining
-                content = " ".join(
-                    str(c.get("text", ""))
-                    for c in msg["content"]
-                    if c and c.get("text") is not None
-                )
+                content = " ".join(c.get("text", "") for c in msg["content"])
            lines.append(content)

            # Handle attachments
@@ -4,14 +4,12 @@ Uses markdown-it with plugins to parse structured data from markdown content.
 """

 from dataclasses import dataclass, field
-from datetime import date, datetime
+from datetime import datetime
 from pathlib import Path
 from typing import Any, Optional

 import dateparser
 import frontmatter
-import yaml
-from loguru import logger
 from markdown_it import MarkdownIt

 from basic_memory.markdown.plugins import observation_plugin, relation_plugin
@@ -26,82 +24,6 @@ from basic_memory.utils import parse_tags
 md = MarkdownIt().use(observation_plugin).use(relation_plugin)


-def normalize_frontmatter_value(value: Any) -> Any:
-    """Normalize frontmatter values to safe types for processing.
-
-    PyYAML automatically converts various string-like values into native Python types:
-    - Date strings ("2025-10-24") → datetime.date objects
-    - Numbers ("1.0") → int or float
-    - Booleans ("true") → bool
-    - Lists → list objects
-
-    This can cause AttributeError when code expects strings and calls string methods
-    like .strip() on these values (see GitHub issue #236).
-
-    This function normalizes all frontmatter values to safe types:
-    - Dates/datetimes → ISO format strings
-    - Numbers (int/float) → strings
-    - Booleans → strings ("True"/"False")
-    - Lists → preserved as lists, but items are recursively normalized
-    - Dicts → preserved as dicts, but values are recursively normalized
-    - Strings → kept as-is
-    - None → kept as None
-
-    Args:
-        value: The frontmatter value to normalize
-
-    Returns:
-        The normalized value safe for string operations
-
-    Example:
-        >>> normalize_frontmatter_value(datetime.date(2025, 10, 24))
-        '2025-10-24'
-        >>> normalize_frontmatter_value([datetime.date(2025, 10, 24), "tag", 123])
-        ['2025-10-24', 'tag', '123']
-        >>> normalize_frontmatter_value(True)
-        'True'
-    """
-    # Convert date/datetime objects to ISO format strings
-    if isinstance(value, datetime):
-        return value.isoformat()
-    if isinstance(value, date):
-        return value.isoformat()
-
-    # Convert boolean to string (must come before int check since bool is subclass of int)
-    if isinstance(value, bool):
-        return str(value)
-
-    # Convert numbers to strings
-    if isinstance(value, (int, float)):
-        return str(value)
-
-    # Recursively process lists (preserve as list, normalize items)
-    if isinstance(value, list):
-        return [normalize_frontmatter_value(item) for item in value]
-
-    # Recursively process dicts (preserve as dict, normalize values)
-    if isinstance(value, dict):
-        return {key: normalize_frontmatter_value(val) for key, val in value.items()}
-
-    # Keep strings and None as-is
-    return value
-
-
-def normalize_frontmatter_metadata(metadata: dict) -> dict:
-    """Normalize all values in frontmatter metadata dict.
-
-    Converts date/datetime objects to ISO format strings to prevent
-    AttributeError when code expects strings (GitHub issue #236).
-
-    Args:
-        metadata: The frontmatter metadata dictionary
-
-    Returns:
-        A new dictionary with all values normalized
-    """
-    return {key: normalize_frontmatter_value(value) for key, value in metadata.items()}
-
-
@dataclass
 class EntityContent:
    content: str
@@ -189,45 +111,18 @@ class EntityParser:
        return self.base_path / path

    async def parse_file_content(self, absolute_path, file_content):
-        # Parse frontmatter with proper error handling for malformed YAML (issue #185)
-        try:
-            post = frontmatter.loads(file_content)
-        except yaml.YAMLError as e:
-            # Log the YAML parsing error with file context
-            logger.warning(
-                f"Failed to parse YAML frontmatter in {absolute_path}: {e}. "
-                f"Treating file as plain markdown without frontmatter."
-            )
-            # Create a post with no frontmatter - treat entire content as markdown
-            post = frontmatter.Post(file_content, metadata={})
-
+        post = frontmatter.loads(file_content)
        # Extract file stat info
        file_stats = absolute_path.stat()
-
-        # Normalize frontmatter values to prevent AttributeError on date objects (issue #236)
-        # PyYAML automatically converts date strings like "2025-10-24" to datetime.date objects
-        # This normalization converts them back to ISO format strings to ensure compatibility
-        # with code that expects string values
-        metadata = normalize_frontmatter_metadata(post.metadata)
-
-        # Ensure required fields have defaults (issue #184, #387)
-        # Handle title - use default if missing, None/null, empty, or string "None"
-        title = metadata.get("title")
-        if not title or title == "None":
-            metadata["title"] = absolute_path.stem
-        else:
-            metadata["title"] = title
-        # Handle type - use default if missing OR explicitly set to None/null
-        entity_type = metadata.get("type")
-        metadata["type"] = entity_type if entity_type is not None else "note"
-
-        tags = parse_tags(metadata.get("tags", []))  # pyright: ignore
+        metadata = post.metadata
+        metadata["title"] = post.metadata.get("title", absolute_path.stem)
+        metadata["type"] = post.metadata.get("type", "note")
+        tags = parse_tags(post.metadata.get("tags", []))  # pyright: ignore
        if tags:
            metadata["tags"] = tags
-
-        # frontmatter - use metadata with defaults applied
+        # frontmatter
        entity_frontmatter = EntityFrontmatter(
-            metadata=metadata,
+            metadata=post.metadata,
        )
        entity_content = parse(post.content)
        return EntityMarkdown(
@@ -1,138 +1,28 @@
-from contextlib import asynccontextmanager, AbstractAsyncContextManager
-from typing import AsyncIterator, Callable, Optional
-
-from httpx import ASGITransport, AsyncClient, Timeout
+import os
+from httpx import ASGITransport, AsyncClient
 from loguru import logger

 from basic_memory.api.app import app as fastapi_app
-from basic_memory.config import ConfigManager
-
-
-# Optional factory override for dependency injection
-_client_factory: Optional[Callable[[], AbstractAsyncContextManager[AsyncClient]]] = None
-
-
-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)
-    """
-    global _client_factory
-    _client_factory = factory
-
-
-@asynccontextmanager
-async def get_client() -> 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
-    """
-    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
-        )
-
-        if config.cloud_mode_enabled:
-            # CLI cloud mode: inject auth when creating client
-            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 not token:
-                raise RuntimeError(
-                    "Cloud mode enabled but not authenticated. "
-                    "Run 'basic-memory cloud login' first."
-                )
-
-            # 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
-            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


 def create_client() -> AsyncClient:
    """Create an HTTP client based on configuration.

-    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
+    proxy_base_url = os.getenv("BASIC_MEMORY_PROXY_URL", None)
+    logger.info(f"BASIC_MEMORY_PROXY_URL: {proxy_base_url}")

-    # 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:
+    if proxy_base_url:
        # 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)
+        return AsyncClient(base_url=proxy_base_url)
    else:
        # Default: use ASGI transport for local API (development mode)
-        logger.info("Creating ASGI client for local Basic Memory API")
-        return AsyncClient(
-            transport=ASGITransport(app=fastapi_app), base_url="http://test", timeout=timeout
-        )
+        logger.debug("Creating ASGI client for local Basic Memory API")
+        return AsyncClient(transport=ASGITransport(app=fastapi_app), base_url="http://test")
+
+
+# Create shared async client
+client = create_client()
@@ -5,30 +5,24 @@ Handles project validation and context management in one place.
 """

 import os
-from typing import Optional, List
+from typing import Optional
 from httpx import AsyncClient
-from httpx._types import (
-    HeaderTypes,
-)
 from loguru import logger
 from fastmcp import Context

 from basic_memory.config import ConfigManager
 from basic_memory.mcp.tools.utils import call_get
-from basic_memory.schemas.project_info import ProjectItem, ProjectList
+from basic_memory.schemas.project_info import ProjectItem
 from basic_memory.utils import generate_permalink


 async def resolve_project_parameter(project: Optional[str] = None) -> Optional[str]:
    """Resolve project parameter using three-tier hierarchy.

-    if config.cloud_mode:
-        project is required
-    else:
-        Resolution order:
-        1. Single Project Mode  (--project cli arg, or BASIC_MEMORY_MCP_PROJECT env var) - highest priority
-        2. Explicit project parameter - medium priority
-        3. Default project if default_project_mode=true - lowest priority
+    Resolution order:
+    1. Single Project Mode  (--project cli arg, or BASIC_MEMORY_MCP_PROJECT env var) - highest priority
+    2. Explicit project parameter - medium priority
+    3. Default project if default_project_mode=true - lowest priority

    Args:
        project: Optional explicit project parameter
@@ -36,16 +30,6 @@ async def resolve_project_parameter(project: Optional[str] = None) -> Optional[s
    Returns:
        Resolved project name or None if no resolution possible
    """
-
-    config = ConfigManager().config
-    # if cloud_mode, project is required
-    if config.cloud_mode:
-        if project:
-            logger.debug(f"project: {project}, cloud_mode: {config.cloud_mode}")
-            return project
-        else:
-            raise ValueError("No project specified. Project is required for cloud mode.")
-
    # Priority 1: CLI constraint overrides everything (--project arg sets env var)
    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
    if constrained_project:
@@ -58,6 +42,7 @@ async def resolve_project_parameter(project: Optional[str] = None) -> Optional[s
        return project

    # Priority 3: Default project mode
+    config = ConfigManager().config
    if config.default_project_mode:
        logger.debug(f"Using default project from config: {config.default_project}")
        return config.default_project
@@ -66,20 +51,16 @@ async def resolve_project_parameter(project: Optional[str] = None) -> Optional[s
    return None


-async def get_project_names(client: AsyncClient, headers: HeaderTypes | None = None) -> List[str]:
-    response = await call_get(client, "/projects/projects", headers=headers)
-    project_list = ProjectList.model_validate(response.json())
-    return [project.name for project in project_list.projects]
-
-
 async def get_active_project(
-    client: AsyncClient,
-    project: Optional[str] = None,
-    context: Optional[Context] = None,
-    headers: HeaderTypes | None = None,
+    client: AsyncClient, project: Optional[str] = None, context: Optional[Context] = None
 ) -> ProjectItem:
    """Get and validate project, setting it in context if available.

+    Uses three-tier resolution:
+    1. CLI constraint (BASIC_MEMORY_MCP_PROJECT env var)
+    2. Explicit project parameter
+    3. Default project if default_project_mode=true
+
    Args:
        client: HTTP client for API calls
        project: Optional project name (resolved using hierarchy)
@@ -92,13 +73,12 @@ async def get_active_project(
        ValueError: If no project can be resolved
        HTTPError: If project doesn't exist or is inaccessible
    """
+    # Resolve project using three-tier hierarchy
    resolved_project = await resolve_project_parameter(project)
    if not resolved_project:
-        project_names = await get_project_names(client, headers)
        raise ValueError(
-            "No project specified. "
-            "Either set 'default_project_mode=true' in config, or use 'project' argument.\n"
-            f"Available projects: {project_names}"
+            "No project specified. Either provide project parameter, "
+            "set default_project_mode=true in config, or use --project constraint."
        )

    project = resolved_project
@@ -113,7 +93,7 @@ async def get_active_project(
    # Validate project exists by calling API
    logger.debug(f"Validating project: {project}")
    permalink = generate_permalink(project)
-    response = await call_get(client, f"/{permalink}/project/item", headers=headers)
+    response = await call_get(client, f"/{permalink}/project/item")
    active_project = ProjectItem.model_validate(response.json())

    # Cache in context if available
@@ -10,7 +10,7 @@ from loguru import logger
 from pydantic import Field

 from basic_memory.config import get_project_config
-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_post
 from basic_memory.schemas.base import TimeFrame
@@ -42,21 +42,20 @@ async def continue_conversation(
    """
    logger.info(f"Continuing session, topic: {topic}, timeframe: {timeframe}")

-    async with get_client() as client:
-        # Create request model
-        request = ContinueConversationRequest(  # pyright: ignore [reportCallIssue]
-            topic=topic, timeframe=timeframe
-        )
+    # Create request model
+    request = ContinueConversationRequest(  # pyright: ignore [reportCallIssue]
+        topic=topic, timeframe=timeframe
+    )

-        project_url = get_project_config().project_url
+    project_url = get_project_config().project_url

-        # Call the prompt API endpoint
-        response = await call_post(
-            client,
-            f"{project_url}/prompt/continue-conversation",
-            json=request.model_dump(exclude_none=True),
-        )
+    # Call the prompt API endpoint
+    response = await call_post(
+        client,
+        f"{project_url}/prompt/continue-conversation",
+        json=request.model_dump(exclude_none=True),
+    )

-        # Extract the rendered prompt from the response
-        result = response.json()
-        return result["prompt"]
+    # Extract the rendered prompt from the response
+    result = response.json()
+    return result["prompt"]
@@ -9,7 +9,7 @@ from loguru import logger
 from pydantic import Field

 from basic_memory.config import get_project_config
-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_post
 from basic_memory.schemas.base import TimeFrame
@@ -41,17 +41,16 @@ async def search_prompt(
    """
    logger.info(f"Searching knowledge base, query: {query}, timeframe: {timeframe}")

-    async with get_client() as client:
-        # Create request model
-        request = SearchPromptRequest(query=query, timeframe=timeframe)
+    # Create request model
+    request = SearchPromptRequest(query=query, timeframe=timeframe)

-        project_url = get_project_config().project_url
+    project_url = get_project_config().project_url

-        # Call the prompt API endpoint
-        response = await call_post(
-            client, f"{project_url}/prompt/search", json=request.model_dump(exclude_none=True)
-        )
+    # Call the prompt API endpoint
+    response = await call_post(
+        client, f"{project_url}/prompt/search", json=request.model_dump(exclude_none=True)
+    )

-        # Extract the rendered prompt from the response
-        result = response.json()
-        return result["prompt"]
+    # Extract the rendered prompt from the response
+    result = response.json()
+    return result["prompt"]
@@ -103,17 +103,10 @@ def format_prompt_context(context: PromptContext) -> str:

                added_permalinks.add(primary_permalink)

-                # Use permalink if available, otherwise use file_path
-                if primary_permalink:
-                    memory_url = normalize_memory_url(primary_permalink)
-                    read_command = f'read_note("{primary_permalink}")'
-                else:
-                    memory_url = f"file://{primary.file_path}"
-                    read_command = f'read_file("{primary.file_path}")'
-
+                memory_url = normalize_memory_url(primary_permalink)
                section = dedent(f"""
                    --- {memory_url}
-
+                
                    ## {primary.title}
                    - **Type**: {primary.type}
                    """)
@@ -128,8 +121,8 @@ def format_prompt_context(context: PromptContext) -> str:
                        section += f"\n**Excerpt**:\n{content}\n"

                section += dedent(f"""
-
-                    You can read this document with: `{read_command}`
+    
+                    You can read this document with: `read_note("{primary_permalink}")`
                    """)
                sections.append(section)

@@ -1,283 +1,551 @@
 # AI Assistant Guide for Basic Memory

-Quick reference for using Basic Memory tools effectively through MCP.
-
-**For comprehensive coverage**: See the [Extended AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) with detailed examples, advanced patterns, and self-contained sections.
+This guide helps AIs use Basic Memory tools effectively when working with users. It covers reading, writing, and
+navigating knowledge through the Model Context Protocol (MCP).

 ## Overview

-Basic Memory creates a semantic knowledge graph from markdown files. Focus on building rich connections between notes.
+Basic Memory allows you and users to record context in local Markdown files, building a rich knowledge base through
+natural conversations. The system automatically creates a semantic knowledge graph from simple text patterns.

- **Local-First**: Plain text files on user's computer
- **Persistent**: Knowledge survives across sessions
- **Semantic**: Observations and relations create a knowledge graph
+- **Local-First**: All data is stored in plain text files on the user's computer
+- **Real-Time**: Users see content updates immediately
+- **Bi-Directional**: Both you and users can read and edit notes
+- **Semantic**: Simple patterns create a structured knowledge graph
+- **Persistent**: Knowledge persists across sessions and conversations

-**Your role**: You're helping humans build enduring knowledge they'll own forever. The semantic graph (observations, relations, context) helps you provide better assistance by understanding connections and maintaining continuity. Think: lasting insights worth keeping, not disposable chat logs.
+## Project Management and Configuration

-## Project Management 
+Basic Memory uses a **stateless architecture** where each tool call can specify which project to work with. This provides three ways to determine the active project:

-All tools require explicit project specification.
+### Three-Tier Project Resolution

-**Three-tier resolution:**
-1. CLI constraint: `--project name` (highest priority)
-2. Explicit parameter: `project="name"` in tool calls
-3. Default mode: `default_project_mode=true` in config (fallback)
-
-### Quick Setup Check
-
-```python
-# Discover projects
-projects = await list_memory_projects()
-
-# Check if default_project_mode enabled
-# If yes: project parameter optional
-# If no: project parameter required
-```
+1. **CLI Constraint (Highest Priority)**: When Basic Memory is started with `--project project-name`, all operations are constrained to that project
+2. **Explicit Project Parameter (Medium Priority)**: When you specify `project="project-name"` in tool calls
+3. **Default Project Mode (Lowest Priority)**: When `default_project_mode=true` in configuration, tools automatically use the configured `default_project`

 ### Default Project Mode

-When `default_project_mode=true`:
+When `default_project_mode` is enabled in the user's configuration:
+- All tools become more convenient - no need to specify project repeatedly
+- Perfect for users who primarily work with a single project
+- Still allows explicit project specification when needed
+- Falls back gracefully to multi-project mode if no default is configured
+
 ```python
-# These are equivalent:
-await write_note("Note", "Content", "folder")
-await write_note("Note", "Content", "folder", project="main")
+# With default_project_mode enabled, these are equivalent:
+await write_note("My Note", "Content", "folder")
+await write_note("My Note", "Content", "folder", project="default-project")
+
+# You can still override with explicit project:
+await write_note("My Note", "Content", "folder", project="other-project")
 ```

-When `default_project_mode=false` (default):
+### Project Discovery
+
+If you're unsure which project to use:
 ```python
-# Project required:
-await write_note("Note", "Content", "folder", project="main")  # ✓
-await write_note("Note", "Content", "folder")  # ✗ Error
+# Discover available projects
+projects = await list_memory_projects()
+
+# See recent activity across projects for recommendations
+activity = await recent_activity()  # Shows cross-project activity and suggestions
 ```

-## Core Tools
+## The Importance of the Knowledge Graph

-### Writing Knowledge
+**Basic Memory's value comes from connections between notes, not just the notes themselves.**
+
+When writing notes, your primary goal should be creating a rich, interconnected knowledge graph:
+
+1. **Increase Semantic Density**: Add multiple observations and relations to each note
+2. **Use Accurate References**: Aim to reference existing entities by their exact titles
+3. **Create Forward References**: Feel free to reference entities that don't exist yet - Basic Memory will resolve these
+   when they're created later
+4. **Create Bidirectional Links**: When appropriate, connect entities from both directions
+5. **Use Meaningful Categories**: Add semantic context with appropriate observation categories
+6. **Choose Precise Relations**: Use specific relation types that convey meaning
+
+Remember: A knowledge graph with 10 heavily connected notes is more valuable than 20 isolated notes. Your job is to help
+build these connections!
+
+## Core Tools Reference
+
+### Knowledge Creation and Editing

 ```python
-await write_note(
-    title="Topic",
-    content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]",
-    folder="notes",
-    project="main"  # Required unless default_project_mode=true
+# Writing knowledge - THE MOST IMPORTANT TOOL!
+response = await write_note(
+    title="Search Design",  # Required: Note title
+    content="# Search Design\n...",  # Required: Note content
+    folder="specs",  # Required: Folder to save in
+    tags=["search", "design"],  # Optional: Tags for categorization
+    project="my-project"  # Optional: Explicit project (uses default if not specified)
+)
+
+# Editing existing notes
+await edit_note(
+    identifier="Search Design",  # Required: Note to edit
+    operation="append",  # Required: append, prepend, find_replace, replace_section
+    content="\n## New Section\nAdditional content",  # Required: Content to add/replace
+    project="my-project"  # Optional: Explicit project
+)
+
+# Moving notes
+await move_note(
+    identifier="Search Design",  # Required: Note to move
+    destination_path="archive/old-search-design.md",  # Required: New location
+    project="my-project"  # Optional: Explicit project
+)
+
+# Deleting notes
+success = await delete_note(
+    identifier="Old Draft",  # Required: Note to delete
+    project="my-project"  # Optional: Explicit project
 )
 ```

-### Reading Knowledge
+### Knowledge Reading and Discovery

 ```python
-# By identifier
-content = await read_note("Topic", project="main")
+# Reading knowledge
+content = await read_note("Search Design")  # By title (uses default project)
+content = await read_note("specs/search-design")  # By path
+content = await read_note("memory://specs/search")  # By memory URL
+content = await read_note("Search Design", project="work-docs")  # Explicit project

-# By memory:// URL
-content = await read_note("memory://folder/topic", project="main")
+# Reading raw file content (text, images, binaries)
+file_data = await read_content(
+    path="assets/diagram.png",  # Required: File path
+    project="my-project"  # Optional: Explicit project
+)
+
+# Viewing notes as formatted artifacts
+await view_note(
+    identifier="Search Design",  # Required: Note to view
+    project="my-project",  # Optional: Explicit project
+    page=1,  # Optional: Pagination
+    page_size=10  # Optional: Items per page
+)
+
+# Browsing directory contents
+listing = await list_directory(
+    dir_name="/specs",  # Optional: Directory path (default: "/")
+    depth=2,  # Optional: Recursion depth
+    file_name_glob="*.md",  # Optional: File pattern filter
+    project="my-project"  # Optional: Explicit project
+)
 ```

-### Searching
+### Search and Context

 ```python
+# Searching for knowledge
 results = await search_notes(
-    query="authentication",
-    project="main",
-    page_size=10
+    query="authentication system",  # Required: Text to search for
+    project="my-project",  # Optional: Explicit project
+    page=1,  # Optional: Pagination
+    page_size=10,  # Optional: Results per page
+    search_type="text",  # Optional: "text", "title", or "permalink"
+    types=["entity"],  # Optional: Filter by content types
+    entity_types=["observation"],  # Optional: Filter by entity types
+    after_date="1 week"  # Optional: Recent content only
 )
-```

-### Building Context
-
-```python
+# Building context from the knowledge graph
 context = await build_context(
-    url="memory://specs/auth",
-    project="main",
-    depth=2,
-    timeframe="1 week"
+    url="memory://specs/search",  # Required: Starting point
+    project="my-project",  # Optional: Explicit project
+    depth=2,  # Optional: How many hops to follow
+    timeframe="1 month",  # Optional: Recent timeframe
+    max_related=10  # Optional: Max related items
+)
+
+# Checking recent changes
+activity = await recent_activity(
+    type=["entity", "relation"],  # Optional: Entity types to include
+    depth=1,  # Optional: Related items to include
+    timeframe="1 week",  # Optional: Time window
+    project="my-project"  # Optional: Explicit project (None for cross-project discovery)
 )
 ```

-## Knowledge Graph Essentials
+### Visualization and Project Management

-### Observations
-
-Categorized facts with optional tags:
-```markdown
- [decision] Use JWT for authentication #security
- [technique] Hash passwords with bcrypt #best-practice
- [requirement] Support OAuth 2.0 providers
-```
-
-### Relations
-
-Directional links between entities:
-```markdown
- implements [[Authentication Spec]]
- requires [[User Database]]
- extends [[Base Security Model]]
-```
-
-**Common relation types:** `relates_to`, `implements`, `requires`, `extends`, `part_of`, `contrasts_with`
-
-### Forward References
-
-Reference entities that don't exist yet:
 ```python
-# Create note with forward reference
-await write_note(
-    title="Login Flow",
-    content="## Relations\n- requires [[OAuth Provider]]",  # Doesn't exist yet
-    folder="auth",
-    project="main"
+# Creating a knowledge visualization
+canvas_result = await canvas(
+    nodes=[{"id": "note1", "type": "file", "file": "Search Design.md"}],  # Required: Nodes
+    edges=[{"id": "edge1", "fromNode": "note1", "toNode": "note2"}],  # Required: Edges
+    title="Project Overview",  # Required: Canvas title
+    folder="diagrams",  # Required: Storage location
+    project="my-project"  # Optional: Explicit project
 )

-# Later, create referenced entity
-await write_note(
-    title="OAuth Provider",
-    content="# OAuth Provider\n...",
-    folder="auth",
-    project="main"
-)
-# → Relation automatically resolved
+# Project management
+projects = await list_memory_projects()  # List all available projects
+project_info = await project_info(project="my-project")  # Get project statistics
 ```

+## memory:// URLs Explained
+
+Basic Memory uses a special URL format to reference entities in the knowledge graph:
+
+- `memory://title` - Reference by title
+- `memory://folder/title` - Reference by folder and title
+- `memory://permalink` - Reference by permalink
+- `memory://path/relation_type/*` - Follow all relations of a specific type
+- `memory://path/*/target` - Find all entities with relations to target
+
+## Semantic Markdown Format
+
+Knowledge is encoded in standard markdown using simple patterns:
+
+**Observations** - Facts about an entity:
+
+```markdown
+- [category] This is an observation #tag1 #tag2 (optional context)
+```
+
+**Relations** - Links between entities:
+
+```markdown
+- relation_type [[Target Entity]] (optional context)
+```
+
+**Common Categories & Relation Types:**
+
+- Categories: `[idea]`, `[decision]`, `[question]`, `[fact]`, `[requirement]`, `[technique]`, `[recipe]`, `[preference]`
+- Relations: `relates_to`, `implements`, `requires`, `extends`, `part_of`, `pairs_with`, `inspired_by`,
+  `originated_from`
+
+## When to Record Context
+
+**Always consider recording context when**:
+
+1. Users make decisions or reach conclusions
+2. Important information emerges during conversation
+3. Multiple related topics are discussed
+4. The conversation contains information that might be useful later
+5. Plans, tasks, or action items are mentioned
+
+**Protocol for recording context**:
+
+1. Identify valuable information in the conversation
+2. Ask the user: "Would you like me to record our discussion about [topic] in Basic Memory?"
+3. If they agree, use `write_note` to capture the information
+4. If they decline, continue without recording
+5. Let the user know when information has been recorded: "I've saved our discussion about [topic] to Basic Memory."
+
+## Understanding User Interactions
+
+Users will interact with Basic Memory in patterns like:
+
+1. **Creating knowledge**:
+   ```
+   Human: "Let's write up what we discussed about search."
+
+   You: I'll create a note capturing our discussion about the search functionality.
+   await write_note(
+       title="Search Functionality Discussion",
+       content="# Search Functionality Discussion\n...",
+       folder="discussions"
+   )
+   ```
+
+2. **Referencing existing knowledge**:
+   ```
+   Human: "Take a look at memory://specs/search"
+
+   You: I'll examine that information.
+   context = await build_context(url="memory://specs/search")
+   content = await read_note("specs/search")
+   ```
+
+3. **Finding information**:
+   ```
+   Human: "What were our decisions about auth?"
+
+   You: Let me find that information for you.
+   results = await search_notes(query="auth decisions")
+   context = await build_context(url=f"memory://{results[0].permalink}")
+   ```
+
+## Key Things to Remember
+
+1. **Files are Truth**
+    - All knowledge lives in local files on the user's computer
+    - Users can edit files outside your interaction
+    - Changes need to be synced by the user (usually automatic)
+    - Always verify information is current with `recent_activity()`
+
+2. **Building Context Effectively**
+    - Start with specific entities
+    - Follow meaningful relations
+    - Check recent changes
+    - Build context incrementally
+    - Combine related information
+
+3. **Writing Knowledge Wisely**
+    - Using the same title+folder will overwrite existing notes
+    - Structure content with clear headings and sections
+    - Use semantic markup for observations and relations
+    - Keep files organized in logical folders
+
+## Common Knowledge Patterns
+
+### Capturing Decisions
+
+```markdown
+# Coffee Brewing Methods
+
+## Context
+
+I've experimented with various brewing methods including French press, pour over, and espresso.
+
+## Decision
+
+Pour over is my preferred method for light to medium roasts because it highlights subtle flavors and offers more control
+over the extraction.
+
+## Observations
+
+- [technique] Blooming the coffee grounds for 30 seconds improves extraction #brewing
+- [preference] Water temperature between 195-205°F works best #temperature
+- [equipment] Gooseneck kettle provides better control of water flow #tools
+
+## Relations
+
+- pairs_with [[Light Roast Beans]]
+- contrasts_with [[French Press Method]]
+- requires [[Proper Grinding Technique]]
+```
+
+### Recording Project Structure
+
+```markdown
+# Garden Planning
+
+## Overview
+
+This document outlines the garden layout and planting strategy for this season.
+
+## Observations
+
+- [structure] Raised beds in south corner for sun exposure #layout
+- [structure] Drip irrigation system installed for efficiency #watering
+- [pattern] Companion planting used to deter pests naturally #technique
+
+## Relations
+
+- contains [[Vegetable Section]]
+- contains [[Herb Garden]]
+- implements [[Organic Gardening Principles]]
+```
+
+### Technical Discussions
+
+```markdown
+# Recipe Improvement Discussion
+
+## Key Points
+
+Discussed strategies for improving the chocolate chip cookie recipe.
+
+## Observations
+
+- [issue] Cookies spread too thin when baked at 350°F #texture
+- [solution] Chilling dough for 24 hours improves flavor and reduces spreading #technique
+- [decision] Will use brown butter instead of regular butter #flavor
+
+## Relations
+
+- improves [[Basic Cookie Recipe]]
+- inspired_by [[Bakery-Style Cookies]]
+- pairs_with [[Homemade Ice Cream]]
+```
+
+### Creating Effective Relations
+
+When creating relations, you can:
+
+1. Reference existing entities by their exact title
+2. Create forward references to entities that don't exist yet
+
+```python
+# Example workflow for creating notes with effective relations
+async def create_note_with_effective_relations():
+    # Search for existing entities to reference
+    search_results = await search_notes(query="travel")
+    existing_entities = [result.title for result in search_results.primary_results]
+
+    # Check if specific entities exist
+    packing_tips_exists = "Packing Tips" in existing_entities
+    japan_travel_exists = "Japan Travel Guide" in existing_entities
+
+    # Prepare relations section - include both existing and forward references
+    relations_section = "## Relations\n"
+
+    # Existing reference - exact match to known entity
+    if packing_tips_exists:
+        relations_section += "- references [[Packing Tips]]\n"
+    else:
+        # Forward reference - will be linked when that entity is created later
+        relations_section += "- references [[Packing Tips]]\n"
+
+    # Another possible reference
+    if japan_travel_exists:
+        relations_section += "- part_of [[Japan Travel Guide]]\n"
+
+    # You can also check recently modified notes to reference them
+    recent = await recent_activity(timeframe="1 week")
+    recent_titles = [item.title for item in recent.primary_results]
+
+    if "Transportation Options" in recent_titles:
+        relations_section += "- relates_to [[Transportation Options]]\n"
+
+    # Always include meaningful forward references, even if they don't exist yet
+    relations_section += "- located_in [[Tokyo]]\n"
+    relations_section += "- visited_during [[Spring 2023 Trip]]\n"
+
+    # Now create the note with both verified and forward relations
+    content = f"""# Tokyo Neighborhood Guide
+
+## Overview
+Details about different Tokyo neighborhoods and their unique characteristics.
+
+## Observations
+- [area] Shibuya is a busy shopping district #shopping
+- [transportation] Yamanote Line connects major neighborhoods #transit
+- [recommendation] Visit Shimokitazawa for vintage shopping #unique
+- [tip] Get a Suica card for easy train travel #convenience
+
+{relations_section}
+    """
+
+    result = await write_note(
+        title="Tokyo Neighborhood Guide",
+        content=content,
+        folder="travel"
+    )
+
+    # You can check which relations were resolved and which are forward references
+    if result and 'relations' in result:
+        resolved = [r['to_name'] for r in result['relations'] if r.get('target_id')]
+        forward_refs = [r['to_name'] for r in result['relations'] if not r.get('target_id')]
+
+        print(f"Resolved relations: {resolved}")
+        print(f"Forward references that will be resolved later: {forward_refs}")
+```
+
+## Error Handling
+
+Common issues to watch for:
+
+1. **Missing Content**
+   ```python
+   try:
+       content = await read_note("Document")
+   except:
+       # Try search instead
+       results = await search_notes(query="Document")
+       if results and results.primary_results:
+           # Found something similar
+           content = await read_note(results.primary_results[0].permalink)
+   ```
+
+2. **Forward References (Unresolved Relations)**
+   ```python
+   response = await write_note(
+       title="My Note",
+       content="Content with [[Forward Reference]]",
+       folder="notes"
+   )
+   # Check for forward references (unresolved relations)
+   forward_refs = []
+   for relation in response.get('relations', []):
+       if not relation.get('target_id'):
+           forward_refs.append(relation.get('to_name'))
+
+   if forward_refs:
+       # This is a feature, not an error! Inform the user about forward references
+       print(f"Note created with forward references to: {forward_refs}")
+       print("These will be automatically linked when those notes are created.")
+
+       # Optionally suggest creating those entities now
+       print("Would you like me to create any of these notes now to complete the connections?")
+   ```
+
+3. **Project Discovery Issues**
+   ```python
+   # If user asks about content but no default project is configured
+   try:
+       results = await search_notes(query="user query")
+   except Exception as e:
+       if "project" in str(e).lower():
+           # Show available projects and ask user to choose
+           projects = await list_memory_projects()
+           print(f"Available projects: {[p.name for p in projects]}")
+           print("Which project should I search in?")
+   ```
+
+4. **Sync Issues**
+   ```python
+   # If information seems outdated
+   activity = await recent_activity(timeframe="1 hour")
+   if not activity or not activity.primary_results:
+       print("It seems there haven't been recent updates. You might need to run 'basic-memory sync'.")
+   ```
+
 ## Best Practices

-### 1. Project Management
+1. **Smart Project Management**
+    - **For new users**: Call `recent_activity()` without project parameter to discover active projects and get recommendations
+    - **For known projects**: Use explicit project parameters when switching between multiple projects
+    - **For single-project users**: Rely on default_project_mode for convenience
+    - **When uncertain**: Use `list_memory_projects()` to show available options and ask the user
+    - **Remember choices**: Once a user indicates their preferred project, use it consistently throughout the conversation

-**Single-project users:**
- Enable `default_project_mode=true`
- Simpler tool calls
+2. **Proactively Record Context**
+    - Offer to capture important discussions
+    - Record decisions, rationales, and conclusions
+    - Link to related topics
+    - Ask for permission first: "Would you like me to save our discussion about [topic]?"
+    - Confirm when complete: "I've saved our discussion to Basic Memory"

-**Multi-project users:**
- Keep `default_project_mode=false`
- Always specify project explicitly
+3. **Create a Rich Semantic Graph**
+    - **Add meaningful observations**: Include at least 3-5 categorized observations in each note
+    - **Create deliberate relations**: Connect each note to at least 2-3 related entities
+    - **Use existing entities**: Before creating a new relation, search for existing entities
+    - **Verify wikilinks**: When referencing `[[Entity]]`, use exact titles of existing notes
+    - **Check accuracy**: Use `search_notes()` or `recent_activity()` to confirm entity titles
+    - **Use precise relation types**: Choose specific relation types that convey meaning (e.g., "implements" instead
+      of "relates_to")
+    - **Consider bidirectional relations**: When appropriate, create inverse relations in both entities

-**Discovery:**
-```python
-# Start with discovery
-projects = await list_memory_projects()
+4. **Structure Content Thoughtfully**
+    - Use clear, descriptive titles
+    - Organize with logical sections (Context, Decision, Implementation, etc.)
+    - Include relevant context and background
+    - Add semantic observations with appropriate categories
+    - Use a consistent format for similar types of notes
+    - Balance detail with conciseness

-# Cross-project activity (no project param = all projects)
-activity = await recent_activity()
+5. **Navigate Knowledge Effectively**
+    - Start with specific searches using `search_notes()`
+    - Follow relation paths with `build_context()`
+    - Combine information from multiple sources
+    - Verify information is current with `recent_activity()`
+    - Build a complete picture before responding
+    - Use appropriate project context for searches

-# Or specific project
-activity = await recent_activity(project="main")
-```
+6. **Help Users Maintain Their Knowledge**
+    - Suggest organizing related topics across projects when appropriate
+    - Identify potential duplicates using search
+    - Recommend adding relations between topics
+    - Offer to create summaries of scattered information
+    - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that connection?"
+    - Help users decide when to use explicit vs default project parameters

-### 2. Building Rich Graphs
-
-**Always include:**
- 3-5 observations per note
- 2-3 relations per note
- Meaningful categories and relation types
-
-**Search before creating:**
-```python
-# Find existing entities to reference
-results = await search_notes(query="authentication", project="main")
-# Use exact titles in [[WikiLinks]]
-```
-
-### 3. Writing Effective Notes
-
-**Structure:**
-```markdown
-# Title
-
-## Context
-Background information
-
-## Observations
- [category] Fact with #tags
- [category] Another fact
-
-## Relations
- relation_type [[Exact Entity Title]]
-```
-
-**Categories:** `[idea]`, `[decision]`, `[fact]`, `[technique]`, `[requirement]`
-
-### 4. Error Handling
-
-**Missing project:**
-```python
-try:
-    await search_notes(query="test")  # Missing project parameter - will error
-except:
-    # Show available projects
-    projects = await list_memory_projects()
-    # Then retry with project
-    results = await search_notes(query="test", project=projects[0].name)
-```
-
-**Forward references:**
-```python
-# Check response for unresolved relations
-response = await write_note(
-    title="New Topic",
-    content="## Relations\n- relates_to [[Future Topic]]",
-    folder="notes",
-    project="main"
-)
-# Forward refs will resolve when target created
-```
-
-### 5. Recording Context
-
-**Ask permission:**
-> "Would you like me to save our discussion about [topic] to Basic Memory?"
-
-**Confirm when done:**
-> "I've saved our discussion to Basic Memory."
-
-**What to record:**
- Decisions and rationales
- Important discoveries
- Action items and plans
- Connected topics
-
-## Common Patterns
-
-### Capture Decision
-
-```python
-await write_note(
-    title="DB Choice",
-    content="""# DB Choice\n## Decision\nUse PostgreSQL\n## Observations\n- [requirement] ACID compliance #reliability\n- [decision] PostgreSQL over MySQL\n## Relations\n- implements [[Data Architecture]]""",
-    folder="decisions",
-    project="main"
-)
-```
-
-### Link Topics & Build Context
-
-```python
-# Link bidirectionally
-await write_note(title="API Auth", content="## Relations\n- part_of [[API Design]]", folder="api", project="main")
-await edit_note(identifier="API Design", operation="append", content="\n- includes [[API Auth]]", project="main")
-
-# Search and build context
-results = await search_notes(query="authentication", project="main")
-context = await build_context(url=f"memory://{results[0].permalink}", project="main", depth=2)
-```
-
-## Tool Quick Reference
-
-| Tool | Purpose | Key Params |
-|------|---------|------------|
-| `write_note` | Create/update | title, content, folder, project |
-| `read_note` | Read content | identifier, project |
-| `edit_note` | Modify existing | identifier, operation, content, project |
-| `search_notes` | Find notes | query, project |
-| `build_context` | Graph traversal | url, depth, project |
-| `recent_activity` | Recent changes | timeframe, project |
-| `list_memory_projects` | Show projects | (none) |
-
-## memory:// URL Format
-
- `memory://title` - By title
- `memory://folder/title` - By folder + title
- `memory://permalink` - By permalink
- `memory://folder/*` - All in folder
-
-For full documentation: https://docs.basicmemory.com
-
-Built with ♥️ by Basic Machines
+Built with ♥️ b
+y Basic Machines
@@ -5,7 +5,7 @@ from typing import Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
@@ -59,13 +59,11 @@ async def project_info(
        print(f"Basic Memory version: {info.system.version}")
    """
    logger.info("Getting project info")
+    project_config = await get_active_project(client, project, context)
+    project_url = project_config.permalink

-    async with get_client() as client:
-        project_config = await get_active_project(client, project, context)
-        project_url = project_config.permalink
+    # Call the API endpoint
+    response = await call_get(client, f"{project_url}/project/info")

-        # Call the API endpoint
-        response = await call_get(client, f"{project_url}/project/info")
-
-        # Convert response to ProjectInfoResponse
-        return ProjectInfoResponse.model_validate(response.json())
+    # Convert response to ProjectInfoResponse
+    return ProjectInfoResponse.model_validate(response.json())
@@ -2,8 +2,39 @@
 Basic Memory FastMCP server.
 """

+import asyncio
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import AsyncIterator, Optional, Any
+
 from fastmcp import FastMCP

+from basic_memory.config import ConfigManager
+from basic_memory.services.initialization import initialize_app
+
+
+@dataclass
+class AppContext:
+    watch_task: Optional[asyncio.Task]
+    migration_manager: Optional[Any] = None
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:  # pragma: no cover
+    """ """
+    app_config = ConfigManager().config
+    # Initialize on startup (now returns migration_manager)
+    migration_manager = await initialize_app(app_config)
+
+    try:
+        yield AppContext(watch_task=None, migration_manager=migration_manager)
+    finally:
+        # Cleanup on shutdown - migration tasks will be cancelled automatically
+        pass
+
+
+# Create the shared server instance with custom Stytch auth
 mcp = FastMCP(
    name="Basic Memory",
+    lifespan=app_lifespan,
 )
@@ -0,0 +1,254 @@
+"""Tool call history tracking for MCP operations."""
+
+import asyncio
+import json
+import time
+from collections import deque
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timedelta
+from typing import Any, Callable, Deque, Dict, List, Optional, TypeVar
+from functools import wraps
+
+# Type variable for generic function type
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass
+class ToolCall:
+    """Represents a single tool call in history."""
+
+    id: str
+    timestamp: float
+    tool_name: str
+    status: str  # "success", "error", "running"
+    execution_time_ms: Optional[float] = None
+    input: Optional[Dict[str, Any]] = None
+    output: Optional[Any] = None
+    error: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = asdict(self)
+        # Convert timestamp to ISO format
+        result["timestamp"] = datetime.fromtimestamp(self.timestamp).isoformat() + "Z"
+        return result
+
+
+class ToolHistoryTracker:
+    """Singleton tracker for tool call history."""
+
+    _instance: Optional["ToolHistoryTracker"] = None
+    _lock = asyncio.Lock()
+
+    def __new__(cls) -> "ToolHistoryTracker":
+        """Ensure singleton instance."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self, max_history: int = 1000):
+        """Initialize the tracker with a maximum history size."""
+        if self._initialized:
+            return
+
+        self.max_history = max_history
+        self.history: Deque[ToolCall] = deque(maxlen=max_history)
+        self._call_counter = 0
+        self._lock = asyncio.Lock()
+        self._initialized = True
+
+    async def add_call(
+        self,
+        tool_name: str,
+        input_params: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """Add a new tool call to history and return its ID."""
+        async with self._lock:
+            self._call_counter += 1
+            call_id = f"call_{self._call_counter:06d}_{int(time.time() * 1000)}"
+
+            tool_call = ToolCall(
+                id=call_id,
+                timestamp=time.time(),
+                tool_name=tool_name,
+                status="running",
+                input=input_params,
+            )
+
+            self.history.append(tool_call)
+            return call_id
+
+    async def update_call(
+        self,
+        call_id: str,
+        status: str,
+        execution_time_ms: Optional[float] = None,
+        output: Optional[Any] = None,
+        error: Optional[str] = None,
+    ):
+        """Update an existing tool call with results."""
+        async with self._lock:
+            for call in self.history:
+                if call.id == call_id:
+                    call.status = status
+                    call.execution_time_ms = execution_time_ms
+                    call.output = output
+                    call.error = error
+                    break
+
+    async def get_history(
+        self,
+        limit: int = 10,
+        tool_name: Optional[str] = None,
+        include_inputs: bool = True,
+        include_outputs: bool = False,
+        since: Optional[str] = None,
+    ) -> List[ToolCall]:
+        """Get filtered tool call history."""
+        async with self._lock:
+            # Convert to list for filtering
+            calls = list(self.history)
+
+            # Filter by time if specified
+            if since:
+                cutoff_time = self._parse_time_filter(since)
+                calls = [c for c in calls if c.timestamp >= cutoff_time]
+
+            # Filter by tool name if specified
+            if tool_name:
+                calls = [c for c in calls if c.tool_name == tool_name]
+
+            # Sort by timestamp (most recent first)
+            calls.sort(key=lambda x: x.timestamp, reverse=True)
+
+            # Limit results
+            calls = calls[:limit]
+
+            # Process outputs based on flags
+            result = []
+            for call in calls:
+                call_copy = ToolCall(
+                    id=call.id,
+                    timestamp=call.timestamp,
+                    tool_name=call.tool_name,
+                    status=call.status,
+                    execution_time_ms=call.execution_time_ms,
+                    input=call.input if include_inputs else None,
+                    output=call.output if include_outputs else None,
+                    error=call.error,
+                )
+                result.append(call_copy)
+
+            return result
+
+    def _parse_time_filter(self, since: str) -> float:
+        """Parse time filter string and return timestamp."""
+        now = time.time()
+
+        # Handle relative times like "1h ago", "2d ago"
+        if "ago" in since.lower():
+            parts = since.lower().replace("ago", "").strip().split()
+            if len(parts) == 1:
+                value_unit = parts[0]
+                # Try to parse combined format like "1h"
+                import re
+                match = re.match(r"(\d+)([hdmw])", value_unit)
+                if match:
+                    value = int(match.group(1))
+                    unit = match.group(2)
+                else:
+                    return now
+            elif len(parts) == 2:
+                value = int(parts[0])
+                unit = parts[1][0]  # First letter of unit
+            else:
+                return now
+
+            if unit == "h":  # hours
+                return now - (value * 3600)
+            elif unit == "d":  # days
+                return now - (value * 86400)
+            elif unit == "m":  # minutes
+                return now - (value * 60)
+            elif unit == "w":  # weeks
+                return now - (value * 604800)
+
+        # Handle absolute dates like "2024-01-20"
+        try:
+            dt = datetime.fromisoformat(since)
+            return dt.timestamp()
+        except:
+            pass
+
+        # Default to current time if parsing fails
+        return now
+
+    async def clear_history(self):
+        """Clear all tool call history."""
+        async with self._lock:
+            self.history.clear()
+            self._call_counter = 0
+
+    async def get_call_by_id(self, call_id: str) -> Optional[ToolCall]:
+        """Get a specific tool call by ID."""
+        async with self._lock:
+            for call in self.history:
+                if call.id == call_id:
+                    return call
+            return None
+
+
+def track_tool_call(func: F) -> F:
+    """Decorator to track MCP tool calls."""
+
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        """Wrapper that tracks tool execution."""
+        tracker = ToolHistoryTracker()
+
+        # Extract tool name from function
+        tool_name = func.__name__
+
+        # Filter out Context parameter if present
+        filtered_kwargs = {k: v for k, v in kwargs.items() if k != "context"}
+
+        # Record the call
+        call_id = await tracker.add_call(tool_name, filtered_kwargs)
+
+        # Execute the tool
+        start_time = time.time()
+        try:
+            result = await func(*args, **kwargs)
+            execution_time = (time.time() - start_time) * 1000
+
+            # Update with success
+            await tracker.update_call(
+                call_id,
+                status="success",
+                execution_time_ms=execution_time,
+                output=result if isinstance(result, (str, int, float, bool)) else str(result)[:500],
+            )
+
+            return result
+
+        except Exception as e:
+            execution_time = (time.time() - start_time) * 1000
+
+            # Update with error
+            await tracker.update_call(
+                call_id,
+                status="error",
+                execution_time_ms=execution_time,
+                error=str(e),
+            )
+
+            raise
+
+    return wrapper  # type: ignore
+
+
+# Singleton instance getter for convenience
+def get_tracker() -> ToolHistoryTracker:
+    """Get the singleton ToolHistoryTracker instance."""
+    return ToolHistoryTracker()
@@ -18,23 +18,27 @@ from basic_memory.mcp.tools.canvas import canvas
 from basic_memory.mcp.tools.list_directory import list_directory
 from basic_memory.mcp.tools.edit_note import edit_note
 from basic_memory.mcp.tools.move_note import move_note
+from basic_memory.mcp.tools.sync_status import sync_status
 from basic_memory.mcp.tools.project_management import (
    list_memory_projects,
    create_memory_project,
    delete_project,
 )
-
 # ChatGPT-compatible tools
 from basic_memory.mcp.tools.chatgpt_tools import search, fetch
+# Tool history tracking
+from basic_memory.mcp.tools.tool_history import tool_history, get_tool_call, clear_tool_history

 __all__ = [
    "build_context",
    "canvas",
+    "clear_tool_history",
    "create_memory_project",
    "delete_note",
    "delete_project",
    "edit_note",
    "fetch",
+    "get_tool_call",
    "list_directory",
    "list_memory_projects",
    "move_note",
@@ -43,6 +47,8 @@ __all__ = [
    "recent_activity",
    "search",
    "search_notes",
+    "sync_status",
+    "tool_history",
    "view_note",
    "write_note",
 ]
@@ -5,7 +5,7 @@ from typing import Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
@@ -16,6 +16,8 @@ from basic_memory.schemas.memory import (
    memory_url_path,
 )

+type StringOrInt = str | int
+

@mcp.tool(
    description="""Build context from a memory:// URI to continue conversations naturally.
@@ -37,7 +39,7 @@ from basic_memory.schemas.memory import (
 async def build_context(
    url: MemoryUrl,
    project: Optional[str] = None,
-    depth: str | int | None = 1,
+    depth: Optional[StringOrInt] = 1,
    timeframe: Optional[TimeFrame] = "7d",
    page: int = 1,
    page_size: int = 10,
@@ -100,21 +102,42 @@ async def build_context(

    # URL is already validated and normalized by MemoryUrl type annotation

-    async with get_client() as client:
-        # Get the active project using the new stateless approach
-        active_project = await get_active_project(client, project, context)
+    # Get the active project using the new stateless approach
+    active_project = await get_active_project(client, project, context)

-        project_url = active_project.project_url
+    # Check migration status and wait briefly if needed
+    from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status

-        response = await call_get(
-            client,
-            f"{project_url}/memory/{memory_url_path(url)}",
-            params={
-                "depth": depth,
-                "timeframe": timeframe,
-                "page": page,
-                "page_size": page_size,
-                "max_related": max_related,
-            },
+    migration_status = await wait_for_migration_or_return_status(
+        timeout=5.0, project_name=active_project.name
+    )
+    if migration_status:  # pragma: no cover
+        # Return a proper GraphContext with status message
+        from basic_memory.schemas.memory import MemoryMetadata
+        from datetime import datetime
+
+        return GraphContext(
+            results=[],
+            metadata=MemoryMetadata(
+                depth=depth or 1,
+                timeframe=timeframe,
+                generated_at=datetime.now().astimezone(),
+                primary_count=0,
+                related_count=0,
+                uri=migration_status,  # Include status in metadata
+            ),
        )
-        return GraphContext.model_validate(response.json())
+    project_url = active_project.project_url
+
+    response = await call_get(
+        client,
+        f"{project_url}/memory/{memory_url_path(url)}",
+        params={
+            "depth": depth,
+            "timeframe": timeframe,
+            "page": page,
+            "page_size": page_size,
+            "max_related": max_related,
+        },
+    )
+    return GraphContext.model_validate(response.json())
@@ -9,7 +9,7 @@ from typing import Dict, List, Any, Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put
@@ -94,37 +94,29 @@ async def canvas(
    Raises:
        ToolError: If project doesn't exist or folder path is invalid
    """
-    async with get_client() as client:
-        active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
+    active_project = await get_active_project(client, project, context)
+    project_url = active_project.project_url

-        # Ensure path has .canvas extension
-        file_title = title if title.endswith(".canvas") else f"{title}.canvas"
-        file_path = f"{folder}/{file_title}"
+    # Ensure path has .canvas extension
+    file_title = title if title.endswith(".canvas") else f"{title}.canvas"
+    file_path = f"{folder}/{file_title}"

-        # Create canvas data structure
-        canvas_data = {"nodes": nodes, "edges": edges}
+    # Create canvas data structure
+    canvas_data = {"nodes": nodes, "edges": edges}

-        # Convert to JSON
-        canvas_json = json.dumps(canvas_data, indent=2)
+    # Convert to JSON
+    canvas_json = json.dumps(canvas_data, indent=2)

-        # Write the file using the resource API
-        logger.info(f"Creating canvas file: {file_path} in project {project}")
-        # Send canvas_json as content string, not as json parameter
-        # The resource endpoint expects Body() string content, not JSON-encoded data
-        response = await call_put(
-            client,
-            f"{project_url}/resource/{file_path}",
-            content=canvas_json,
-            headers={"Content-Type": "text/plain"},
-        )
+    # Write the file using the resource API
+    logger.info(f"Creating canvas file: {file_path} in project {project}")
+    response = await call_put(client, f"{project_url}/resource/{file_path}", json=canvas_json)

-        # Parse response
-        result = response.json()
-        logger.debug(result)
+    # Parse response
+    result = response.json()
+    logger.debug(result)

-        # Build summary
-        action = "Created" if response.status_code == 201 else "Updated"
-        summary = [f"# {action}: {file_path}", "\nThe canvas is ready to open in Obsidian."]
+    # Build summary
+    action = "Created" if response.status_code == 201 else "Updated"
+    summary = [f"# {action}: {file_path}", "\nThe canvas is ready to open in Obsidian."]

-        return "\n".join(summary)
+    return "\n".join(summary)
@@ -14,7 +14,6 @@ from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.read_note import read_note
 from basic_memory.schemas.search import SearchResponse
-from basic_memory.config import ConfigManager


 def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str, Any]]:
@@ -28,7 +27,7 @@ def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str
        formatted_result = {
            "id": result.permalink or f"doc-{len(formatted_results)}",
            "title": result.title if result.title and result.title.strip() else "Untitled",
-            "url": result.permalink or "",
+            "url": result.permalink or ""
        }
        formatted_results.append(formatted_result)

@@ -44,11 +43,11 @@ def _format_document_for_chatgpt(
    """
    # Extract title from markdown content if not provided
    if not title and isinstance(content, str):
-        lines = content.split("\n")
-        if lines and lines[0].startswith("# "):
+        lines = content.split('\n')
+        if lines and lines[0].startswith('# '):
            title = lines[0][2:].strip()
        else:
-            title = identifier.split("/")[-1].replace("-", " ").title()
+            title = identifier.split('/')[-1].replace('-', ' ').title()

    # Ensure title is never None
    if not title:
@@ -61,7 +60,7 @@ def _format_document_for_chatgpt(
            "title": title or "Document Not Found",
            "text": content,
            "url": identifier,
-            "metadata": {"error": "Document not found"},
+            "metadata": {"error": "Document not found"}
        }

    return {
@@ -69,11 +68,13 @@ def _format_document_for_chatgpt(
        "title": title or "Untitled Document",
        "text": content,
        "url": identifier,
-        "metadata": {"format": "markdown"},
+        "metadata": {"format": "markdown"}
    }


-@mcp.tool(description="Search for content across the knowledge base")
+@mcp.tool(
+    description="Search for content across the knowledge base"
+)
 async def search(
    query: str,
    context: Context | None = None,
@@ -91,18 +92,14 @@ async def search(
    logger.info(f"ChatGPT search request: query='{query}'")

    try:
-        # ChatGPT tools don't expose project parameter, so use default project
-        config = ConfigManager().config
-        default_project = config.default_project
-
        # Call underlying search_notes with sensible defaults for ChatGPT
        results = await search_notes.fn(
            query=query,
-            project=default_project,  # Use default project for ChatGPT
+            project=None,  # Let project resolution happen automatically
            page=1,
            page_size=10,  # Reasonable default for ChatGPT consumption
            search_type="text",  # Default to full-text search
-            context=context,
+            context=context
        )

        # Handle string error responses from search_notes
@@ -111,7 +108,7 @@ async def search(
            search_results = {
                "results": [],
                "error": "Search failed",
-                "error_details": results[:500],  # Truncate long error messages
+                "error_details": results[:500]  # Truncate long error messages
            }
        else:
            # Format successful results for ChatGPT
@@ -119,24 +116,36 @@ async def search(
            search_results = {
                "results": formatted_results,
                "total_count": len(results.results),  # Use actual count from results
-                "query": query,
+                "query": query
            }
            logger.info(f"Search completed: {len(formatted_results)} results returned")

        # Return in MCP content array format as required by OpenAI
-        return [{"type": "text", "text": json.dumps(search_results, ensure_ascii=False)}]
+        return [
+            {
+                "type": "text",
+                "text": json.dumps(search_results, ensure_ascii=False)
+            }
+        ]

    except Exception as e:
        logger.error(f"ChatGPT search failed for query '{query}': {e}")
        error_results = {
            "results": [],
            "error": "Internal search error",
-            "error_message": str(e)[:200],
+            "error_message": str(e)[:200]
        }
-        return [{"type": "text", "text": json.dumps(error_results, ensure_ascii=False)}]
+        return [
+            {
+                "type": "text",
+                "text": json.dumps(error_results, ensure_ascii=False)
+            }
+        ]


-@mcp.tool(description="Fetch the full contents of a search result document")
+@mcp.tool(
+    description="Fetch the full contents of a search result document"
+)
 async def fetch(
    id: str,
    context: Context | None = None,
@@ -154,17 +163,13 @@ async def fetch(
    logger.info(f"ChatGPT fetch request: id='{id}'")

    try:
-        # ChatGPT tools don't expose project parameter, so use default project
-        config = ConfigManager().config
-        default_project = config.default_project
-
        # Call underlying read_note function
        content = await read_note.fn(
            identifier=id,
-            project=default_project,  # Use default project for ChatGPT
+            project=None,  # Let project resolution happen automatically
            page=1,
            page_size=10,  # Default pagination
-            context=context,
+            context=context
        )

        # Format the document for ChatGPT
@@ -173,7 +178,12 @@ async def fetch(
        logger.info(f"Fetch completed: id='{id}', content_length={len(document.get('text', ''))}")

        # Return in MCP content array format as required by OpenAI
-        return [{"type": "text", "text": json.dumps(document, ensure_ascii=False)}]
+        return [
+            {
+                "type": "text",
+                "text": json.dumps(document, ensure_ascii=False)
+            }
+        ]

    except Exception as e:
        logger.error(f"ChatGPT fetch failed for id '{id}': {e}")
@@ -182,6 +192,11 @@ async def fetch(
            "title": "Fetch Error",
            "text": f"Failed to fetch document: {str(e)[:200]}",
            "url": id,
-            "metadata": {"error": "Fetch failed"},
+            "metadata": {"error": "Fetch failed"}
        }
-        return [{"type": "text", "text": json.dumps(error_document, ensure_ascii=False)}]
+        return [
+            {
+                "type": "text",
+                "text": json.dumps(error_document, ensure_ascii=False)
+            }
+        ]
@@ -7,7 +7,7 @@ from fastmcp import Context
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.tools.utils import call_delete
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.schemas import DeleteEntitiesResponse


@@ -202,24 +202,23 @@ async def delete_note(
        with suggestions for finding the correct identifier, including search
        commands and alternative formats to try.
    """
-    async with get_client() as client:
-        active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
+    active_project = await get_active_project(client, project, context)
+    project_url = active_project.project_url

-        try:
-            response = await call_delete(client, f"{project_url}/knowledge/entities/{identifier}")
-            result = DeleteEntitiesResponse.model_validate(response.json())
+    try:
+        response = await call_delete(client, f"{project_url}/knowledge/entities/{identifier}")
+        result = DeleteEntitiesResponse.model_validate(response.json())

-            if result.deleted:
-                logger.info(
-                    f"Successfully deleted note: {identifier} in project: {active_project.name}"
-                )
-                return True
-            else:
-                logger.warning(f"Delete operation completed but note was not deleted: {identifier}")
-                return False
+        if result.deleted:
+            logger.info(
+                f"Successfully deleted note: {identifier} in project: {active_project.name}"
+            )
+            return True
+        else:
+            logger.warning(f"Delete operation completed but note was not deleted: {identifier}")
+            return False

-        except Exception as e:  # pragma: no cover
-            logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")
-            # Return formatted error message for better user experience
-            return _format_delete_error_response(active_project.name, str(e), identifier)
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")
+        # Return formatted error message for better user experience
+        return _format_delete_error_response(active_project.name, str(e), identifier)
@@ -5,7 +5,7 @@ from typing import Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.project_context import get_active_project, add_project_metadata
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_patch
@@ -214,107 +214,106 @@ async def edit_note(
        search_notes() first to find the correct identifier. The tool provides detailed
        error messages with suggestions if operations fail.
    """
-    async with get_client() as client:
-        active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
+    active_project = await get_active_project(client, project, context)
+    project_url = active_project.project_url

-        logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation)
+    logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation)

-        # Validate operation
-        valid_operations = ["append", "prepend", "find_replace", "replace_section"]
-        if operation not in valid_operations:
-            raise ValueError(
-                f"Invalid operation '{operation}'. Must be one of: {', '.join(valid_operations)}"
-            )
+    # Validate operation
+    valid_operations = ["append", "prepend", "find_replace", "replace_section"]
+    if operation not in valid_operations:
+        raise ValueError(
+            f"Invalid operation '{operation}'. Must be one of: {', '.join(valid_operations)}"
+        )

-        # Validate required parameters for specific operations
-        if operation == "find_replace" and not find_text:
-            raise ValueError("find_text parameter is required for find_replace operation")
-        if operation == "replace_section" and not section:
-            raise ValueError("section parameter is required for replace_section operation")
+    # Validate required parameters for specific operations
+    if operation == "find_replace" and not find_text:
+        raise ValueError("find_text parameter is required for find_replace operation")
+    if operation == "replace_section" and not section:
+        raise ValueError("section parameter is required for replace_section operation")

-        # Use the PATCH endpoint to edit the entity
-        try:
-            # Prepare the edit request data
-            edit_data = {
-                "operation": operation,
-                "content": content,
-            }
+    # Use the PATCH endpoint to edit the entity
+    try:
+        # Prepare the edit request data
+        edit_data = {
+            "operation": operation,
+            "content": content,
+        }

-            # Add optional parameters
-            if section:
-                edit_data["section"] = section
-            if find_text:
-                edit_data["find_text"] = find_text
-            if expected_replacements != 1:  # Only send if different from default
-                edit_data["expected_replacements"] = str(expected_replacements)
+        # Add optional parameters
+        if section:
+            edit_data["section"] = section
+        if find_text:
+            edit_data["find_text"] = find_text
+        if expected_replacements != 1:  # Only send if different from default
+            edit_data["expected_replacements"] = str(expected_replacements)

-            # Call the PATCH endpoint
-            url = f"{project_url}/knowledge/entities/{identifier}"
-            response = await call_patch(client, url, json=edit_data)
-            result = EntityResponse.model_validate(response.json())
+        # Call the PATCH endpoint
+        url = f"{project_url}/knowledge/entities/{identifier}"
+        response = await call_patch(client, url, json=edit_data)
+        result = EntityResponse.model_validate(response.json())

-            # Format summary
-            summary = [
-                f"# Edited note ({operation})",
-                f"project: {active_project.name}",
-                f"file_path: {result.file_path}",
-                f"permalink: {result.permalink}",
-                f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
-            ]
+        # Format summary
+        summary = [
+            f"# Edited note ({operation})",
+            f"project: {active_project.name}",
+            f"file_path: {result.file_path}",
+            f"permalink: {result.permalink}",
+            f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+        ]

-            # Add operation-specific details
-            if operation == "append":
-                lines_added = len(content.split("\n"))
-                summary.append(f"operation: Added {lines_added} lines to end of note")
-            elif operation == "prepend":
-                lines_added = len(content.split("\n"))
-                summary.append(f"operation: Added {lines_added} lines to beginning of note")
-            elif operation == "find_replace":
-                # For find_replace, we can't easily count replacements from here
-                # since we don't have the original content, but the server handled it
-                summary.append("operation: Find and replace operation completed")
-            elif operation == "replace_section":
-                summary.append(f"operation: Replaced content under section '{section}'")
+        # Add operation-specific details
+        if operation == "append":
+            lines_added = len(content.split("\n"))
+            summary.append(f"operation: Added {lines_added} lines to end of note")
+        elif operation == "prepend":
+            lines_added = len(content.split("\n"))
+            summary.append(f"operation: Added {lines_added} lines to beginning of note")
+        elif operation == "find_replace":
+            # For find_replace, we can't easily count replacements from here
+            # since we don't have the original content, but the server handled it
+            summary.append("operation: Find and replace operation completed")
+        elif operation == "replace_section":
+            summary.append(f"operation: Replaced content under section '{section}'")

-            # Count observations by category (reuse logic from write_note)
-            categories = {}
-            if result.observations:
-                for obs in result.observations:
-                    categories[obs.category] = categories.get(obs.category, 0) + 1
+        # Count observations by category (reuse logic from write_note)
+        categories = {}
+        if result.observations:
+            for obs in result.observations:
+                categories[obs.category] = categories.get(obs.category, 0) + 1

-                summary.append("\\n## Observations")
-                for category, count in sorted(categories.items()):
-                    summary.append(f"- {category}: {count}")
+            summary.append("\\n## Observations")
+            for category, count in sorted(categories.items()):
+                summary.append(f"- {category}: {count}")

-            # Count resolved/unresolved relations
-            unresolved = 0
-            resolved = 0
-            if result.relations:
-                unresolved = sum(1 for r in result.relations if not r.to_id)
-                resolved = len(result.relations) - unresolved
+        # Count resolved/unresolved relations
+        unresolved = 0
+        resolved = 0
+        if result.relations:
+            unresolved = sum(1 for r in result.relations if not r.to_id)
+            resolved = len(result.relations) - unresolved

-                summary.append("\\n## Relations")
-                summary.append(f"- Resolved: {resolved}")
-                if unresolved:
-                    summary.append(f"- Unresolved: {unresolved}")
+            summary.append("\\n## Relations")
+            summary.append(f"- Resolved: {resolved}")
+            if unresolved:
+                summary.append(f"- Unresolved: {unresolved}")

-            logger.info(
-                "MCP tool response",
-                tool="edit_note",
-                operation=operation,
-                project=active_project.name,
-                permalink=result.permalink,
-                observations_count=len(result.observations),
-                relations_count=len(result.relations),
-                status_code=response.status_code,
-            )
+        logger.info(
+            "MCP tool response",
+            tool="edit_note",
+            operation=operation,
+            project=active_project.name,
+            permalink=result.permalink,
+            observations_count=len(result.observations),
+            relations_count=len(result.relations),
+            status_code=response.status_code,
+        )

-            result = "\n".join(summary)
-            return add_project_metadata(result, active_project.name)
+        result = "\n".join(summary)
+        return add_project_metadata(result, active_project.name)

-        except Exception as e:
-            logger.error(f"Error editing note: {e}")
-            return _format_error_response(
-                str(e), operation, identifier, find_text, expected_replacements, active_project.name
-            )
+    except Exception as e:
+        logger.error(f"Error editing note: {e}")
+        return _format_error_response(
+            str(e), operation, identifier, find_text, expected_replacements, active_project.name
+        )
@@ -0,0 +1,38 @@
+from httpx._types import (
+    HeaderTypes,
+)
+from loguru import logger
+from fastmcp.server.dependencies import get_http_headers
+
+
+def inject_auth_header(headers: HeaderTypes | None = None) -> HeaderTypes:
+    """
+    Inject JWT token from FastMCP context into headers if available.
+
+    Args:
+        headers: Existing headers dict or None
+
+    Returns:
+        Headers dict with Authorization header added if JWT is available
+    """
+    # Start with existing headers or empty dict
+    if headers is None:
+        headers = {}
+    elif not isinstance(headers, dict):
+        # Convert other header types to dict
+        headers = dict(headers)  # type: ignore
+    else:
+        # Make a copy to avoid modifying the original
+        headers = headers.copy()
+
+    http_headers = get_http_headers()
+    logger.debug(f"HTTP headers: {http_headers}")
+
+    authorization = http_headers.get("Authorization") or http_headers.get("authorization")
+    if authorization:
+        headers["Authorization"] = authorization  # type: ignore
+        logger.debug("Injected JWT token into authorization request headers")
+    else:
+        logger.debug("No authorization found in request headers")
+
+    return headers
@@ -5,7 +5,7 @@ from typing import Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
@@ -63,105 +63,102 @@ async def list_directory(
    Raises:
        ToolError: If project doesn't exist or directory path is invalid
    """
-    async with get_client() as client:
-        active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
+    active_project = await get_active_project(client, project, context)
+    project_url = active_project.project_url

-        # Prepare query parameters
-        params = {
-            "dir_name": dir_name,
-            "depth": str(depth),
-        }
+    # Prepare query parameters
+    params = {
+        "dir_name": dir_name,
+        "depth": str(depth),
+    }
+    if file_name_glob:
+        params["file_name_glob"] = file_name_glob
+
+    logger.debug(
+        f"Listing directory '{dir_name}' in project {project} with depth={depth}, glob='{file_name_glob}'"
+    )
+
+    # Call the API endpoint
+    response = await call_get(
+        client,
+        f"{project_url}/directory/list",
+        params=params,
+    )
+
+    nodes = response.json()
+
+    if not nodes:
+        filter_desc = ""
        if file_name_glob:
-            params["file_name_glob"] = file_name_glob
+            filter_desc = f" matching '{file_name_glob}'"
+        return f"No files found in directory '{dir_name}'{filter_desc}"

-        logger.debug(
-            f"Listing directory '{dir_name}' in project {project} with depth={depth}, glob='{file_name_glob}'"
-        )
+    # Format the results
+    output_lines = []
+    if file_name_glob:
+        output_lines.append(f"Files in '{dir_name}' matching '{file_name_glob}' (depth {depth}):")
+    else:
+        output_lines.append(f"Contents of '{dir_name}' (depth {depth}):")
+    output_lines.append("")

-        # Call the API endpoint
-        response = await call_get(
-            client,
-            f"{project_url}/directory/list",
-            params=params,
-        )
+    # Group by type and sort
+    directories = [n for n in nodes if n["type"] == "directory"]
+    files = [n for n in nodes if n["type"] == "file"]

-        nodes = response.json()
+    # Sort by name
+    directories.sort(key=lambda x: x["name"])
+    files.sort(key=lambda x: x["name"])

-        if not nodes:
-            filter_desc = ""
-            if file_name_glob:
-                filter_desc = f" matching '{file_name_glob}'"
-            return f"No files found in directory '{dir_name}'{filter_desc}"
+    # Display directories first
+    for node in directories:
+        path_display = node["directory_path"]
+        output_lines.append(f"📁 {node['name']:<30} {path_display}")

-        # Format the results
-        output_lines = []
-        if file_name_glob:
-            output_lines.append(
-                f"Files in '{dir_name}' matching '{file_name_glob}' (depth {depth}):"
-            )
-        else:
-            output_lines.append(f"Contents of '{dir_name}' (depth {depth}):")
+    # Add separator if we have both directories and files
+    if directories and files:
        output_lines.append("")

-        # Group by type and sort
-        directories = [n for n in nodes if n["type"] == "directory"]
-        files = [n for n in nodes if n["type"] == "file"]
+    # Display files with metadata
+    for node in files:
+        path_display = node["directory_path"]
+        title = node.get("title", "")
+        updated = node.get("updated_at", "")

-        # Sort by name
-        directories.sort(key=lambda x: x["name"])
-        files.sort(key=lambda x: x["name"])
+        # Remove leading slash if present, requesting the file via read_note does not use the beginning slash'
+        if path_display.startswith("/"):
+            path_display = path_display[1:]

-        # Display directories first
-        for node in directories:
-            path_display = node["directory_path"]
-            output_lines.append(f"📁 {node['name']:<30} {path_display}")
+        # Format date if available
+        date_str = ""
+        if updated:
+            try:
+                from datetime import datetime

-        # Add separator if we have both directories and files
-        if directories and files:
-            output_lines.append("")
+                dt = datetime.fromisoformat(updated.replace("Z", "+00:00"))
+                date_str = dt.strftime("%Y-%m-%d")
+            except Exception:  # pragma: no cover
+                date_str = updated[:10] if len(updated) >= 10 else ""

-        # Display files with metadata
-        for node in files:
-            path_display = node["directory_path"]
-            title = node.get("title", "")
-            updated = node.get("updated_at", "")
+        # Create formatted line
+        file_line = f"📄 {node['name']:<30} {path_display}"
+        if title and title != node["name"]:
+            file_line += f" | {title}"
+        if date_str:
+            file_line += f" | {date_str}"

-            # Remove leading slash if present, requesting the file via read_note does not use the beginning slash'
-            if path_display.startswith("/"):
-                path_display = path_display[1:]
+        output_lines.append(file_line)

-            # Format date if available
-            date_str = ""
-            if updated:
-                try:
-                    from datetime import datetime
+    # Add summary
+    output_lines.append("")
+    total_count = len(directories) + len(files)
+    summary_parts = []
+    if directories:
+        summary_parts.append(
+            f"{len(directories)} director{'y' if len(directories) == 1 else 'ies'}"
+        )
+    if files:
+        summary_parts.append(f"{len(files)} file{'s' if len(files) != 1 else ''}")

-                    dt = datetime.fromisoformat(updated.replace("Z", "+00:00"))
-                    date_str = dt.strftime("%Y-%m-%d")
-                except Exception:  # pragma: no cover
-                    date_str = updated[:10] if len(updated) >= 10 else ""
+    output_lines.append(f"Total: {total_count} items ({', '.join(summary_parts)})")

-            # Create formatted line
-            file_line = f"📄 {node['name']:<30} {path_display}"
-            if title and title != node["name"]:
-                file_line += f" | {title}"
-            if date_str:
-                file_line += f" | {date_str}"
-
-            output_lines.append(file_line)
-
-        # Add summary
-        output_lines.append("")
-        total_count = len(directories) + len(files)
-        summary_parts = []
-        if directories:
-            summary_parts.append(
-                f"{len(directories)} director{'y' if len(directories) == 1 else 'ies'}"
-            )
-        if files:
-            summary_parts.append(f"{len(files)} file{'s' if len(files) != 1 else ''}")
-
-        output_lines.append(f"Total: {total_count} items ({', '.join(summary_parts)})")
-
-        return "\n".join(output_lines)
+    return "\n".join(output_lines)
@@ -6,7 +6,7 @@ from typing import Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_post, call_get
 from basic_memory.mcp.project_context import get_active_project
@@ -16,12 +16,11 @@ from basic_memory.utils import validate_project_path


 async def _detect_cross_project_move_attempt(
-    client, identifier: str, destination_path: str, current_project: str
+    identifier: str, destination_path: str, current_project: str
 ) -> Optional[str]:
    """Detect potential cross-project move attempts and return guidance.

    Args:
-        client: The AsyncClient instance
        identifier: The note identifier being moved
        destination_path: The destination path
        current_project: The current active project
@@ -66,16 +65,16 @@ def _format_cross_project_error_response(
    """Format error response for detected cross-project move attempts."""
    return dedent(f"""
        # Move Failed - Cross-Project Move Not Supported
-
+        
        Cannot move '{identifier}' to '{destination_path}' because it appears to reference a different project ('{target_project}').
-
+        
        **Current project:** {current_project}
        **Target project:** {target_project}
-
+        
        ## Cross-project moves are not supported directly
-
+        
        Notes can only be moved within the same project. To move content between projects, use this workflow:
-
+        
        ### Recommended approach:
        ```
        # 1. Read the note content from current project
@@ -88,13 +87,13 @@ def _format_cross_project_error_response(
        delete_note("{identifier}", project="{current_project}")
        
        ```
-
+        
        ### Alternative: Stay in current project
        If you want to move the note within the **{current_project}** project only:
        ```
        move_note("{identifier}", "new-folder/new-name.md")
        ```
-
+        
        ## Available projects:
        Use `list_memory_projects()` to see all available projects.
        """).strip()
@@ -395,21 +394,20 @@ async def move_note(
    - Re-indexes the entity for search
    - Maintains all observations and relations
    """
-    async with get_client() as client:
-        logger.debug(f"Moving note: {identifier} to {destination_path} in project: {project}")
+    logger.debug(f"Moving note: {identifier} to {destination_path} in project: {project}")

-        active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
+    active_project = await get_active_project(client, project, context)
+    project_url = active_project.project_url

-        # Validate destination path to prevent path traversal attacks
-        project_path = active_project.home
-        if not validate_project_path(destination_path, project_path):
-            logger.warning(
-                "Attempted path traversal attack blocked",
-                destination_path=destination_path,
-                project=active_project.name,
-            )
-            return f"""# Move Failed - Security Validation Error
+    # Validate destination path to prevent path traversal attacks
+    project_path = active_project.home
+    if not validate_project_path(destination_path, project_path):
+        logger.warning(
+            "Attempted path traversal attack blocked",
+            destination_path=destination_path,
+            project=active_project.name,
+        )
+        return f"""# Move Failed - Security Validation Error

 The destination path '{destination_path}' is not allowed - paths must stay within project boundaries.

@@ -423,123 +421,50 @@ The destination path '{destination_path}' is not allowed - paths must stay withi
 move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in destination_path else destination_path}")
 ```"""

-        # Check for potential cross-project move attempts
-        cross_project_error = await _detect_cross_project_move_attempt(
-            client, identifier, destination_path, active_project.name
+    # Check for potential cross-project move attempts
+    cross_project_error = await _detect_cross_project_move_attempt(
+        identifier, destination_path, active_project.name
+    )
+    if cross_project_error:
+        logger.info(f"Detected cross-project move attempt: {identifier} -> {destination_path}")
+        return cross_project_error
+
+    try:
+        # Prepare move request
+        move_data = {
+            "identifier": identifier,
+            "destination_path": destination_path,
+            "project": active_project.name,
+        }
+
+        # Call the move API endpoint
+        url = f"{project_url}/knowledge/move"
+        response = await call_post(client, url, json=move_data)
+        result = EntityResponse.model_validate(response.json())
+
+        # Build success message
+        result_lines = [
+            "✅ Note moved successfully",
+            "",
+            f"📁 **{identifier}** → **{result.file_path}**",
+            f"🔗 Permalink: {result.permalink}",
+            "📊 Database and search index updated",
+            "",
+            f"<!-- Project: {active_project.name} -->",
+        ]
+
+        # Log the operation
+        logger.info(
+            "Move note completed",
+            identifier=identifier,
+            destination_path=destination_path,
+            project=active_project.name,
+            status_code=response.status_code,
        )
-        if cross_project_error:
-            logger.info(f"Detected cross-project move attempt: {identifier} -> {destination_path}")
-            return cross_project_error

-        # Get the source entity information for extension validation
-        source_ext = "md"  # Default to .md if we can't determine source extension
-        try:
-            # Fetch source entity information to get the current file extension
-            url = f"{project_url}/knowledge/entities/{identifier}"
-            response = await call_get(client, url)
-            source_entity = EntityResponse.model_validate(response.json())
-            if "." in source_entity.file_path:
-                source_ext = source_entity.file_path.split(".")[-1]
-        except Exception as e:
-            # If we can't fetch the source entity, default to .md extension
-            logger.debug(f"Could not fetch source entity for extension check: {e}")
+        return "\n".join(result_lines)

-        # Validate that destination path includes a file extension
-        if "." not in destination_path or not destination_path.split(".")[-1]:
-            logger.warning(f"Move failed - no file extension provided: {destination_path}")
-            return dedent(f"""
-                # Move Failed - File Extension Required
-
-                The destination path '{destination_path}' must include a file extension (e.g., '.md').
-
-                ## Valid examples:
-                - `notes/my-note.md`
-                - `projects/meeting-2025.txt`
-                - `archive/old-program.sh`
-
-                ## Try again with extension:
-                ```
-                move_note("{identifier}", "{destination_path}.{source_ext}")
-                ```
-
-                All examples in Basic Memory expect file extensions to be explicitly provided.
-                """).strip()
-
-        # Get the source entity to check its file extension
-        try:
-            # Fetch source entity information
-            url = f"{project_url}/knowledge/entities/{identifier}"
-            response = await call_get(client, url)
-            source_entity = EntityResponse.model_validate(response.json())
-
-            # Extract file extensions
-            source_ext = (
-                source_entity.file_path.split(".")[-1] if "." in source_entity.file_path else ""
-            )
-            dest_ext = destination_path.split(".")[-1] if "." in destination_path else ""
-
-            # Check if extensions match
-            if source_ext and dest_ext and source_ext.lower() != dest_ext.lower():
-                logger.warning(
-                    f"Move failed - file extension mismatch: source={source_ext}, dest={dest_ext}"
-                )
-                return dedent(f"""
-                    # Move Failed - File Extension Mismatch
-
-                    The destination file extension '.{dest_ext}' does not match the source file extension '.{source_ext}'.
-
-                    To preserve file type consistency, the destination must have the same extension as the source.
-
-                    ## Source file:
-                    - Path: `{source_entity.file_path}`
-                    - Extension: `.{source_ext}`
-
-                    ## Try again with matching extension:
-                    ```
-                    move_note("{identifier}", "{destination_path.rsplit(".", 1)[0]}.{source_ext}")
-                    ```
-                    """).strip()
-        except Exception as e:
-            # If we can't fetch the source entity, log it but continue
-            # This might happen if the identifier is not yet resolved
-            logger.debug(f"Could not fetch source entity for extension check: {e}")
-
-        try:
-            # Prepare move request
-            move_data = {
-                "identifier": identifier,
-                "destination_path": destination_path,
-                "project": active_project.name,
-            }
-
-            # Call the move API endpoint
-            url = f"{project_url}/knowledge/move"
-            response = await call_post(client, url, json=move_data)
-            result = EntityResponse.model_validate(response.json())
-
-            # Build success message
-            result_lines = [
-                "✅ Note moved successfully",
-                "",
-                f"📁 **{identifier}** → **{result.file_path}**",
-                f"🔗 Permalink: {result.permalink}",
-                "📊 Database and search index updated",
-                "",
-                f"<!-- Project: {active_project.name} -->",
-            ]
-
-            # Log the operation
-            logger.info(
-                "Move note completed",
-                identifier=identifier,
-                destination_path=destination_path,
-                project=active_project.name,
-                status_code=response.status_code,
-            )
-
-            return "\n".join(result_lines)
-
-        except Exception as e:
-            logger.error(f"Move failed for '{identifier}' to '{destination_path}': {e}")
-            # Return formatted error message for better user experience
-            return _format_move_error_response(str(e), identifier, destination_path)
+    except Exception as e:
+        logger.error(f"Move failed for '{identifier}' to '{destination_path}': {e}")
+        # Return formatted error message for better user experience
+        return _format_move_error_response(str(e), identifier, destination_path)
@@ -7,7 +7,7 @@ and manage project context during conversations.
 import os
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get, call_post, call_delete
 from basic_memory.schemas.project_info import (
@@ -40,35 +40,34 @@ async def list_memory_projects(context: Context | None = None) -> str:
    Example:
        list_memory_projects()
    """
-    async with get_client() as client:
-        if context:  # pragma: no cover
-            await context.info("Listing all available projects")
+    if context:  # pragma: no cover
+        await context.info("Listing all available projects")

-        # Check if server is constrained to a specific project
-        constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+    # Check if server is constrained to a specific project
+    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")

-        # Get projects from API
-        response = await call_get(client, "/projects/projects")
-        project_list = ProjectList.model_validate(response.json())
+    # Get projects from API
+    response = await call_get(client, "/projects/projects")
+    project_list = ProjectList.model_validate(response.json())

-        if constrained_project:
-            result = f"Project: {constrained_project}\n\n"
-            result += "Note: This MCP server is constrained to a single project.\n"
-            result += "All operations will automatically use this project."
-        else:
-            # Show all projects with session guidance
-            result = "Available projects:\n"
+    if constrained_project:
+        result = f"Project: {constrained_project}\n\n"
+        result += "Note: This MCP server is constrained to a single project.\n"
+        result += "All operations will automatically use this project."
+    else:
+        # Show all projects with session guidance
+        result = "Available projects:\n"

-            for project in project_list.projects:
-                result += f"• {project.name}\n"
+        for project in project_list.projects:
+            result += f"• {project.name}\n"

-            result += "\n" + "─" * 40 + "\n"
-            result += "Next: Ask which project to use for this session.\n"
-            result += "Example: 'Which project should I use for this task?'\n\n"
-            result += "Session reminder: Track the selected project for all subsequent operations in this conversation.\n"
-            result += "The user can say 'switch to [project]' to change projects."
+        result += "\n" + "─" * 40 + "\n"
+        result += "Next: Ask which project to use for this session.\n"
+        result += "Example: 'Which project should I use for this task?'\n\n"
+        result += "Session reminder: Track the selected project for all subsequent operations in this conversation.\n"
+        result += "The user can say 'switch to [project]' to change projects."

-        return result
+    return result


@mcp.tool("create_memory_project")
@@ -92,38 +91,37 @@ async def create_memory_project(
        create_memory_project("my-research", "~/Documents/research")
        create_memory_project("work-notes", "/home/user/work", set_default=True)
    """
-    async with get_client() as client:
-        # Check if server is constrained to a specific project
-        constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
-        if constrained_project:
-            return f'# Error\n\nProject creation disabled - MCP server is constrained to project \'{constrained_project}\'.\nUse the CLI to create projects: `basic-memory project add "{project_name}" "{project_path}"`'
+    # Check if server is constrained to a specific project
+    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+    if constrained_project:
+        return f'# Error\n\nProject creation disabled - MCP server is constrained to project \'{constrained_project}\'.\nUse the CLI to create projects: `basic-memory project add "{project_name}" "{project_path}"`'

-        if context:  # pragma: no cover
-            await context.info(f"Creating project: {project_name} at {project_path}")
+    if context:  # pragma: no cover
+        await context.info(f"Creating project: {project_name} at {project_path}")

-        # Create the project request
-        project_request = ProjectInfoRequest(
-            name=project_name, path=project_path, set_default=set_default
-        )
+    # Create the project request
+    project_request = ProjectInfoRequest(
+        name=project_name, path=project_path, set_default=set_default
+    )

-        # Call API to create project
-        response = await call_post(client, "/projects/projects", json=project_request.model_dump())
-        status_response = ProjectStatusResponse.model_validate(response.json())
+    # Call API to create project
+    response = await call_post(client, "/projects/projects", json=project_request.model_dump())
+    status_response = ProjectStatusResponse.model_validate(response.json())

-        result = f"✓ {status_response.message}\n\n"
+    result = f"✓ {status_response.message}\n\n"

-        if status_response.new_project:
-            result += "Project Details:\n"
-            result += f"• Name: {status_response.new_project.name}\n"
-            result += f"• Path: {status_response.new_project.path}\n"
+    if status_response.new_project:
+        result += "Project Details:\n"
+        result += f"• Name: {status_response.new_project.name}\n"
+        result += f"• Path: {status_response.new_project.path}\n"

-            if set_default:
-                result += "• Set as default project\n"
+        if set_default:
+            result += "• Set as default project\n"

-        result += "\nProject is now available for use in tool calls.\n"
-        result += f"Use '{project_name}' as the project parameter in MCP tool calls.\n"
+    result += "\nProject is now available for use in tool calls.\n"
+    result += f"Use '{project_name}' as the project parameter in MCP tool calls.\n"

-        return result
+    return result


@mcp.tool()
@@ -147,54 +145,53 @@ async def delete_project(project_name: str, context: Context | None = None) -> s
        This action cannot be undone. The project will need to be re-added
        to access its content through Basic Memory again.
    """
-    async with get_client() as client:
-        # Check if server is constrained to a specific project
-        constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
-        if constrained_project:
-            return f"# Error\n\nProject deletion disabled - MCP server is constrained to project '{constrained_project}'.\nUse the CLI to delete projects: `basic-memory project remove \"{project_name}\"`"
+    # Check if server is constrained to a specific project
+    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+    if constrained_project:
+        return f"# Error\n\nProject deletion disabled - MCP server is constrained to project '{constrained_project}'.\nUse the CLI to delete projects: `basic-memory project remove \"{project_name}\"`"

-        if context:  # pragma: no cover
-            await context.info(f"Deleting project: {project_name}")
+    if context:  # pragma: no cover
+        await context.info(f"Deleting project: {project_name}")

-        # Get project info before deletion to validate it exists
-        response = await call_get(client, "/projects/projects")
-        project_list = ProjectList.model_validate(response.json())
+    # Get project info before deletion to validate it exists
+    response = await call_get(client, "/projects/projects")
+    project_list = ProjectList.model_validate(response.json())

-        # Find the project by name (case-insensitive) or permalink - same logic as switch_project
-        project_permalink = generate_permalink(project_name)
-        target_project = None
-        for p in project_list.projects:
-            # Match by permalink (handles case-insensitive input)
-            if p.permalink == project_permalink:
-                target_project = p
-                break
-            # Also match by name comparison (case-insensitive)
-            if p.name.lower() == project_name.lower():
-                target_project = p
-                break
+    # Find the project by name (case-insensitive) or permalink - same logic as switch_project
+    project_permalink = generate_permalink(project_name)
+    target_project = None
+    for p in project_list.projects:
+        # Match by permalink (handles case-insensitive input)
+        if p.permalink == project_permalink:
+            target_project = p
+            break
+        # Also match by name comparison (case-insensitive)
+        if p.name.lower() == project_name.lower():
+            target_project = p
+            break

-        if not target_project:
-            available_projects = [p.name for p in project_list.projects]
-            raise ValueError(
-                f"Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
-            )
+    if not target_project:
+        available_projects = [p.name for p in project_list.projects]
+        raise ValueError(
+            f"Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
+        )

-        # Call API to delete project using URL encoding for special characters
-        from urllib.parse import quote
+    # Call API to delete project using URL encoding for special characters
+    from urllib.parse import quote

-        encoded_name = quote(target_project.name, safe="")
-        response = await call_delete(client, f"/projects/{encoded_name}")
-        status_response = ProjectStatusResponse.model_validate(response.json())
+    encoded_name = quote(target_project.name, safe="")
+    response = await call_delete(client, f"/projects/{encoded_name}")
+    status_response = ProjectStatusResponse.model_validate(response.json())

-        result = f"✓ {status_response.message}\n\n"
+    result = f"✓ {status_response.message}\n\n"

-        if status_response.old_project:
-            result += "Removed project details:\n"
-            result += f"• Name: {status_response.old_project.name}\n"
-            if hasattr(status_response.old_project, "path"):
-                result += f"• Path: {status_response.old_project.path}\n"
+    if status_response.old_project:
+        result += "Removed project details:\n"
+        result += f"• Name: {status_response.old_project.name}\n"
+        if hasattr(status_response.old_project, "path"):
+            result += f"• Path: {status_response.old_project.path}\n"

-        result += "Files remain on disk but project is no longer tracked by Basic Memory.\n"
-        result += "Re-add the project to access its content again.\n"
+    result += "Files remain on disk but project is no longer tracked by Basic Memory.\n"
+    result += "Re-add the project to access its content again.\n"

-        return result
+    return result
@@ -16,7 +16,7 @@ from fastmcp import Context

 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.memory import memory_url_path
 from basic_memory.utils import validate_project_path
@@ -201,71 +201,70 @@ async def read_content(
    """
    logger.info("Reading file", path=path, project=project)

-    async with get_client() as client:
-        active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
+    active_project = await get_active_project(client, project, context)
+    project_url = active_project.project_url

-        url = memory_url_path(path)
+    url = memory_url_path(path)

-        # Validate path to prevent path traversal attacks
-        project_path = active_project.home
-        if not validate_project_path(url, project_path):
-            logger.warning(
-                "Attempted path traversal attack blocked",
-                path=path,
-                url=url,
-                project=active_project.name,
-            )
+    # Validate path to prevent path traversal attacks
+    project_path = active_project.home
+    if not validate_project_path(url, project_path):
+        logger.warning(
+            "Attempted path traversal attack blocked",
+            path=path,
+            url=url,
+            project=active_project.name,
+        )
+        return {
+            "type": "error",
+            "error": f"Path '{path}' is not allowed - paths must stay within project boundaries",
+        }
+
+    response = await call_get(client, f"{project_url}/resource/{url}")
+    content_type = response.headers.get("content-type", "application/octet-stream")
+    content_length = int(response.headers.get("content-length", 0))
+
+    logger.debug("Resource metadata", content_type=content_type, size=content_length, path=path)
+
+    # Handle text or json
+    if content_type.startswith("text/") or content_type == "application/json":
+        logger.debug("Processing text resource")
+        return {
+            "type": "text",
+            "text": response.text,
+            "content_type": content_type,
+            "encoding": "utf-8",
+        }
+
+    # Handle images
+    elif content_type.startswith("image/"):
+        logger.debug("Processing image")
+        img = PILImage.open(io.BytesIO(response.content))
+        img_bytes = optimize_image(img, content_length)
+
+        return {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": "image/jpeg",
+                "data": base64.b64encode(img_bytes).decode("utf-8"),
+            },
+        }
+
+    # Handle other file types
+    else:
+        logger.debug(f"Processing binary resource content_type {content_type}")
+        if content_length > 350000:  # pragma: no cover
+            logger.warning("Document too large for response", size=content_length)
            return {
                "type": "error",
-                "error": f"Path '{path}' is not allowed - paths must stay within project boundaries",
-            }
-
-        response = await call_get(client, f"{project_url}/resource/{url}")
-        content_type = response.headers.get("content-type", "application/octet-stream")
-        content_length = int(response.headers.get("content-length", 0))
-
-        logger.debug("Resource metadata", content_type=content_type, size=content_length, path=path)
-
-        # Handle text or json
-        if content_type.startswith("text/") or content_type == "application/json":
-            logger.debug("Processing text resource")
-            return {
-                "type": "text",
-                "text": response.text,
-                "content_type": content_type,
-                "encoding": "utf-8",
-            }
-
-        # Handle images
-        elif content_type.startswith("image/"):
-            logger.debug("Processing image")
-            img = PILImage.open(io.BytesIO(response.content))
-            img_bytes = optimize_image(img, content_length)
-
-            return {
-                "type": "image",
-                "source": {
-                    "type": "base64",
-                    "media_type": "image/jpeg",
-                    "data": base64.b64encode(img_bytes).decode("utf-8"),
-                },
-            }
-
-        # Handle other file types
-        else:
-            logger.debug(f"Processing binary resource content_type {content_type}")
-            if content_length > 350000:  # pragma: no cover
-                logger.warning("Document too large for response", size=content_length)
-                return {
-                    "type": "error",
-                    "error": f"Document size {content_length} bytes exceeds maximum allowed size",
-                }
-            return {
-                "type": "document",
-                "source": {
-                    "type": "base64",
-                    "media_type": content_type,
-                    "data": base64.b64encode(response.content).decode("utf-8"),
-                },
+                "error": f"Document size {content_length} bytes exceeds maximum allowed size",
            }
+        return {
+            "type": "document",
+            "source": {
+                "type": "base64",
+                "media_type": content_type,
+                "data": base64.b64encode(response.content).decode("utf-8"),
+            },
+        }
@@ -6,9 +6,10 @@ from typing import Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tool_history import track_tool_call
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.memory import memory_url_path
@@ -18,6 +19,7 @@ from basic_memory.utils import validate_project_path
@mcp.tool(
    description="Read a markdown note by title or permalink.",
 )
+@track_tool_call
 async def read_note(
    identifier: str,
    project: Optional[str] = None,
@@ -77,88 +79,94 @@ async def read_note(
        If the exact note isn't found, this tool provides helpful suggestions
        including related notes, search commands, and note creation templates.
    """
-    async with get_client() as client:
-        # Get and validate the project
-        active_project = await get_active_project(client, project, context)

-        # Validate identifier to prevent path traversal attacks
-        # We need to check both the raw identifier and the processed path
-        processed_path = memory_url_path(identifier)
-        project_path = active_project.home
+    # Get and validate the project
+    active_project = await get_active_project(client, project, context)

-        if not validate_project_path(identifier, project_path) or not validate_project_path(
-            processed_path, project_path
-        ):
-            logger.warning(
-                "Attempted path traversal attack blocked",
-                identifier=identifier,
-                processed_path=processed_path,
-                project=active_project.name,
-            )
-            return f"# Error\n\nIdentifier '{identifier}' is not allowed - paths must stay within project boundaries"
+    # Validate identifier to prevent path traversal attacks
+    # We need to check both the raw identifier and the processed path
+    processed_path = memory_url_path(identifier)
+    project_path = active_project.home

-        project_url = active_project.project_url
+    if not validate_project_path(identifier, project_path) or not validate_project_path(
+        processed_path, project_path
+    ):
+        logger.warning(
+            "Attempted path traversal attack blocked",
+            identifier=identifier,
+            processed_path=processed_path,
+            project=active_project.name,
+        )
+        return f"# Error\n\nIdentifier '{identifier}' is not allowed - paths must stay within project boundaries"

-        # Get the file via REST API - first try direct permalink lookup
-        entity_path = memory_url_path(identifier)
-        path = f"{project_url}/resource/{entity_path}"
-        logger.info(f"Attempting to read note from Project: {active_project.name} URL: {path}")
+    # Check migration status and wait briefly if needed
+    from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status

-        try:
-            # Try direct lookup first
-            response = await call_get(client, path, params={"page": page, "page_size": page_size})
+    migration_status = await wait_for_migration_or_return_status(
+        timeout=5.0, project_name=active_project.name
+    )
+    if migration_status:  # pragma: no cover
+        return f"# System Status\n\n{migration_status}\n\nPlease wait for migration to complete before reading notes."
+    project_url = active_project.project_url

-            # If successful, return the content
-            if response.status_code == 200:
-                logger.info("Returning read_note result from resource: {path}", path=entity_path)
-                return response.text
-        except Exception as e:  # pragma: no cover
-            logger.info(f"Direct lookup failed for '{path}': {e}")
-            # Continue to fallback methods
+    # Get the file via REST API - first try direct permalink lookup
+    entity_path = memory_url_path(identifier)
+    path = f"{project_url}/resource/{entity_path}"
+    logger.info(f"Attempting to read note from Project: {active_project.name} URL: {path}")

-        # Fallback 1: Try title search via API
-        logger.info(f"Search title for: {identifier}")
-        title_results = await search_notes.fn(
-            query=identifier, search_type="title", project=project, context=context
+    try:
+        # Try direct lookup first
+        response = await call_get(client, path, params={"page": page, "page_size": page_size})
+
+        # If successful, return the content
+        if response.status_code == 200:
+            logger.info("Returning read_note result from resource: {path}", path=entity_path)
+            return response.text
+    except Exception as e:  # pragma: no cover
+        logger.info(f"Direct lookup failed for '{path}': {e}")
+        # Continue to fallback methods
+
+    # Fallback 1: Try title search via API
+    logger.info(f"Search title for: {identifier}")
+    title_results = await search_notes.fn(
+        query=identifier, search_type="title", project=project, context=context
+    )
+
+    if title_results and title_results.results:
+        result = title_results.results[0]  # Get the first/best match
+        if result.permalink:
+            try:
+                # Try to fetch the content using the found permalink
+                path = f"{project_url}/resource/{result.permalink}"
+                response = await call_get(
+                    client, path, params={"page": page, "page_size": page_size}
+                )
+
+                if response.status_code == 200:
+                    logger.info(f"Found note by title search: {result.permalink}")
+                    return response.text
+            except Exception as e:  # pragma: no cover
+                logger.info(
+                    f"Failed to fetch content for found title match {result.permalink}: {e}"
+                )
+    else:
+        logger.info(
+            f"No results in title search for: {identifier} in project {active_project.name}"
        )

-        # Handle both SearchResponse object and error strings
-        if title_results and hasattr(title_results, "results") and title_results.results:
-            result = title_results.results[0]  # Get the first/best match
-            if result.permalink:
-                try:
-                    # Try to fetch the content using the found permalink
-                    path = f"{project_url}/resource/{result.permalink}"
-                    response = await call_get(
-                        client, path, params={"page": page, "page_size": page_size}
-                    )
+    # Fallback 2: Text search as a last resort
+    logger.info(f"Title search failed, trying text search for: {identifier}")
+    text_results = await search_notes.fn(
+        query=identifier, search_type="text", project=project, context=context
+    )

-                    if response.status_code == 200:
-                        logger.info(f"Found note by title search: {result.permalink}")
-                        return response.text
-                except Exception as e:  # pragma: no cover
-                    logger.info(
-                        f"Failed to fetch content for found title match {result.permalink}: {e}"
-                    )
-        else:
-            logger.info(
-                f"No results in title search for: {identifier} in project {active_project.name}"
-            )
-
-        # Fallback 2: Text search as a last resort
-        logger.info(f"Title search failed, trying text search for: {identifier}")
-        text_results = await search_notes.fn(
-            query=identifier, search_type="text", project=project, context=context
-        )
-
-        # We didn't find a direct match, construct a helpful error message
-        # Handle both SearchResponse object and error strings
-        if not text_results or not hasattr(text_results, "results") or not text_results.results:
-            # No results at all
-            return format_not_found_message(active_project.name, identifier)
-        else:
-            # We found some related results
-            return format_related_results(active_project.name, identifier, text_results.results[:5])
+    # We didn't find a direct match, construct a helpful error message
+    if not text_results or not text_results.results:
+        # No results at all
+        return format_not_found_message(active_project.name, identifier)
+    else:
+        # We found some related results
+        return format_related_results(active_project.name, identifier, text_results.results[:5])


 def format_not_found_message(project: str | None, identifier: str) -> str:
@@ -5,7 +5,7 @@ from typing import List, Union, Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.project_context import get_active_project, resolve_project_parameter
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
@@ -98,166 +98,162 @@ async def recent_activity(
        - For focused queries, consider using build_context with a specific URI
        - Max timeframe is 1 year in the past
    """
-    async with get_client() as client:
-        # Build common parameters for API calls
-        params = {
-            "page": 1,
-            "page_size": 10,
-            "max_related": 10,
-        }
-        if depth:
-            params["depth"] = depth
-        if timeframe:
-            params["timeframe"] = timeframe  # pyright: ignore
+    # Build common parameters for API calls
+    params = {
+        "page": 1,
+        "page_size": 10,
+        "max_related": 10,
+    }
+    if depth:
+        params["depth"] = depth
+    if timeframe:
+        params["timeframe"] = timeframe  # pyright: ignore

-        # Validate and convert type parameter
-        if type:
-            # Convert single string to list
-            if isinstance(type, str):
-                type_list = [type]
-            else:
-                type_list = type
+    # Validate and convert type parameter
+    if type:
+        # Convert single string to list
+        if isinstance(type, str):
+            type_list = [type]
+        else:
+            type_list = type

-            # Validate each type against SearchItemType enum
-            validated_types = []
-            for t in type_list:
-                try:
-                    # Try to convert string to enum
-                    if isinstance(t, str):
-                        validated_types.append(SearchItemType(t.lower()))
-                except ValueError:
-                    valid_types = [t.value for t in SearchItemType]
-                    raise ValueError(f"Invalid type: {t}. Valid types are: {valid_types}")
+        # Validate each type against SearchItemType enum
+        validated_types = []
+        for t in type_list:
+            try:
+                # Try to convert string to enum
+                if isinstance(t, str):
+                    validated_types.append(SearchItemType(t.lower()))
+            except ValueError:
+                valid_types = [t.value for t in SearchItemType]
+                raise ValueError(f"Invalid type: {t}. Valid types are: {valid_types}")

-            # Add validated types to params
-            params["type"] = [t.value for t in validated_types]  # pyright: ignore
+        # Add validated types to params
+        params["type"] = [t.value for t in validated_types]  # pyright: ignore

-        # Resolve project parameter using the three-tier hierarchy
-        resolved_project = await resolve_project_parameter(project)
+    # Resolve project parameter using the three-tier hierarchy
+    resolved_project = await resolve_project_parameter(project)

-        if resolved_project is None:
-            # Discovery Mode: Get activity across all projects
-            logger.info(
-                f"Getting recent activity across all projects: type={type}, depth={depth}, timeframe={timeframe}"
-            )
+    if resolved_project is None:
+        # Discovery Mode: Get activity across all projects
+        logger.info(
+            f"Getting recent activity across all projects: type={type}, depth={depth}, timeframe={timeframe}"
+        )

-            # Get list of all projects
-            response = await call_get(client, "/projects/projects")
-            project_list = ProjectList.model_validate(response.json())
+        # Get list of all projects
+        response = await call_get(client, "/projects/projects")
+        project_list = ProjectList.model_validate(response.json())

-            projects_activity = {}
-            total_items = 0
-            total_entities = 0
-            total_relations = 0
-            total_observations = 0
-            most_active_project = None
-            most_active_count = 0
-            active_projects = 0
+        projects_activity = {}
+        total_items = 0
+        total_entities = 0
+        total_relations = 0
+        total_observations = 0
+        most_active_project = None
+        most_active_count = 0
+        active_projects = 0

-            # Query each project's activity
-            for project_info in project_list.projects:
-                project_activity = await _get_project_activity(client, project_info, params, depth)
-                projects_activity[project_info.name] = project_activity
+        # Query each project's activity
+        for project_info in project_list.projects:
+            project_activity = await _get_project_activity(client, project_info, params, depth)
+            projects_activity[project_info.name] = project_activity

-                # Aggregate stats
-                item_count = project_activity.item_count
-                if item_count > 0:
-                    active_projects += 1
-                    total_items += item_count
+            # Aggregate stats
+            item_count = project_activity.item_count
+            if item_count > 0:
+                active_projects += 1
+                total_items += item_count

-                    # Count by type
-                    for result in project_activity.activity.results:
-                        if result.primary_result.type == "entity":
-                            total_entities += 1
-                        elif result.primary_result.type == "relation":
-                            total_relations += 1
-                        elif result.primary_result.type == "observation":
-                            total_observations += 1
+                # Count by type
+                for result in project_activity.activity.results:
+                    if result.primary_result.type == "entity":
+                        total_entities += 1
+                    elif result.primary_result.type == "relation":
+                        total_relations += 1
+                    elif result.primary_result.type == "observation":
+                        total_observations += 1

-                    # Track most active project
-                    if item_count > most_active_count:
-                        most_active_count = item_count
-                        most_active_project = project_info.name
+                # Track most active project
+                if item_count > most_active_count:
+                    most_active_count = item_count
+                    most_active_project = project_info.name

-            # Build summary stats
-            summary = ActivityStats(
-                total_projects=len(project_list.projects),
-                active_projects=active_projects,
-                most_active_project=most_active_project,
-                total_items=total_items,
-                total_entities=total_entities,
-                total_relations=total_relations,
-                total_observations=total_observations,
-            )
+        # Build summary stats
+        summary = ActivityStats(
+            total_projects=len(project_list.projects),
+            active_projects=active_projects,
+            most_active_project=most_active_project,
+            total_items=total_items,
+            total_entities=total_entities,
+            total_relations=total_relations,
+            total_observations=total_observations,
+        )

-            # Generate guidance for the assistant
-            guidance_lines = ["\n" + "─" * 40]
-
-            if most_active_project and most_active_count > 0:
-                guidance_lines.extend(
-                    [
-                        f"Suggested project: '{most_active_project}' (most active with {most_active_count} items)",
-                        f"Ask user: 'Should I use {most_active_project} for this task, or would you prefer a different project?'",
-                    ]
-                )
-            elif active_projects > 0:
-                # Has activity but no clear most active project
-                active_project_names = [
-                    name for name, activity in projects_activity.items() if activity.item_count > 0
-                ]
-                if len(active_project_names) == 1:
-                    guidance_lines.extend(
-                        [
-                            f"Suggested project: '{active_project_names[0]}' (only active project)",
-                            f"Ask user: 'Should I use {active_project_names[0]} for this task?'",
-                        ]
-                    )
-                else:
-                    guidance_lines.extend(
-                        [
-                            f"Multiple active projects found: {', '.join(active_project_names)}",
-                            "Ask user: 'Which project should I use for this task?'",
-                        ]
-                    )
-            else:
-                # No recent activity
-                guidance_lines.extend(
-                    [
-                        "No recent activity found in any project.",
-                        "Consider: Ask which project to use or if they want to create a new one.",
-                    ]
-                )
+        # Generate guidance for the assistant
+        guidance_lines = ["\n" + "─" * 40]

+        if most_active_project and most_active_count > 0:
            guidance_lines.extend(
                [
-                    "",
-                    "Session reminder: Remember their project choice throughout this conversation.",
+                    f"Suggested project: '{most_active_project}' (most active with {most_active_count} items)",
+                    f"Ask user: 'Should I use {most_active_project} for this task, or would you prefer a different project?'",
+                ]
+            )
+        elif active_projects > 0:
+            # Has activity but no clear most active project
+            active_project_names = [
+                name for name, activity in projects_activity.items() if activity.item_count > 0
+            ]
+            if len(active_project_names) == 1:
+                guidance_lines.extend(
+                    [
+                        f"Suggested project: '{active_project_names[0]}' (only active project)",
+                        f"Ask user: 'Should I use {active_project_names[0]} for this task?'",
+                    ]
+                )
+            else:
+                guidance_lines.extend(
+                    [
+                        f"Multiple active projects found: {', '.join(active_project_names)}",
+                        "Ask user: 'Which project should I use for this task?'",
+                    ]
+                )
+        else:
+            # No recent activity
+            guidance_lines.extend(
+                [
+                    "No recent activity found in any project.",
+                    "Consider: Ask which project to use or if they want to create a new one.",
                ]
            )

-            guidance = "\n".join(guidance_lines)
+        guidance_lines.extend(
+            ["", "Session reminder: Remember their project choice throughout this conversation."]
+        )

-            # Format discovery mode output
-            return _format_discovery_output(projects_activity, summary, timeframe, guidance)
+        guidance = "\n".join(guidance_lines)

-        else:
-            # Project-Specific Mode: Get activity for specific project
-            logger.info(
-                f"Getting recent activity from project {resolved_project}: type={type}, depth={depth}, timeframe={timeframe}"
-            )
+        # Format discovery mode output
+        return _format_discovery_output(projects_activity, summary, timeframe, guidance)

-            active_project = await get_active_project(client, resolved_project, context)
-            project_url = active_project.project_url
+    else:
+        # Project-Specific Mode: Get activity for specific project
+        logger.info(
+            f"Getting recent activity from project {resolved_project}: type={type}, depth={depth}, timeframe={timeframe}"
+        )

-            response = await call_get(
-                client,
-                f"{project_url}/memory/recent",
-                params=params,
-            )
-            activity_data = GraphContext.model_validate(response.json())
+        active_project = await get_active_project(client, resolved_project, context)
+        project_url = active_project.project_url

-            # Format project-specific mode output
-            return _format_project_output(resolved_project, activity_data, timeframe, type)
+        response = await call_get(
+            client,
+            f"{project_url}/memory/recent",
+            params=params,
+        )
+        activity_data = GraphContext.model_validate(response.json())
+
+        # Format project-specific mode output
+        return _format_project_output(resolved_project, activity_data, timeframe, type)


 async def _get_project_activity(
@@ -6,9 +6,10 @@ from typing import List, Optional
 from loguru import logger
 from fastmcp import Context

-from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tool_history import track_tool_call
 from basic_memory.mcp.tools.utils import call_post
 from basic_memory.schemas.search import SearchItemType, SearchQuery, SearchResponse

@@ -199,14 +200,15 @@ Error searching for '{query}': {error_message}
@mcp.tool(
    description="Search across all content in the knowledge base with advanced syntax support.",
 )
+@track_tool_call
 async def search_notes(
    query: str,
    project: Optional[str] = None,
    page: int = 1,
    page_size: int = 10,
    search_type: str = "text",
-    types: List[str] = [],
-    entity_types: List[str] = [],
+    types: Optional[List[str]] = None,
+    entity_types: Optional[List[str]] = None,
    after_date: Optional[str] = None,
    context: Context | None = None,
 ) -> SearchResponse | str:
@@ -345,7 +347,7 @@ async def search_notes(
    else:
        search_query.text = query  # Default to text search

-    # Add optional filters if provided (empty lists are treated as no filter)
+    # Add optional filters if provided
    if entity_types:
        search_query.entity_types = [SearchItemType(t) for t in entity_types]
    if types:
@@ -353,32 +355,31 @@ async def search_notes(
    if after_date:
        search_query.after_date = after_date

-    async with get_client() as client:
-        active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
+    active_project = await get_active_project(client, project, context)
+    project_url = active_project.project_url

-        logger.info(f"Searching for {search_query} in project {active_project.name}")
+    logger.info(f"Searching for {search_query} in project {active_project.name}")

-        try:
-            response = await call_post(
-                client,
-                f"{project_url}/search/",
-                json=search_query.model_dump(),
-                params={"page": page, "page_size": page_size},
+    try:
+        response = await call_post(
+            client,
+            f"{project_url}/search/",
+            json=search_query.model_dump(),
+            params={"page": page, "page_size": page_size},
+        )
+        result = SearchResponse.model_validate(response.json())
+
+        # Check if we got no results and provide helpful guidance
+        if not result.results:
+            logger.info(
+                f"Search returned no results for query: {query} in project {active_project.name}"
            )
-            result = SearchResponse.model_validate(response.json())
+            # Don't treat this as an error, but the user might want guidance
+            # We return the empty result as normal - the user can decide if they need help

-            # Check if we got no results and provide helpful guidance
-            if not result.results:
-                logger.info(
-                    f"Search returned no results for query: {query} in project {active_project.name}"
-                )
-                # Don't treat this as an error, but the user might want guidance
-                # We return the empty result as normal - the user can decide if they need help
+        return result

-            return result
-
-        except Exception as e:
-            logger.error(f"Search failed for query '{query}': {e}, project: {active_project.name}")
-            # Return formatted error message as string for better user experience
-            return _format_search_error_response(active_project.name, str(e), query, search_type)
+    except Exception as e:
+        logger.error(f"Search failed for query '{query}': {e}, project: {active_project.name}")
+        # Return formatted error message as string for better user experience
+        return _format_search_error_response(active_project.name, str(e), query, search_type)
@@ -0,0 +1,257 @@
+"""Sync status tool for Basic Memory MCP server."""
+
+from typing import Optional
+
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.config import ConfigManager
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.project_context import get_active_project
+from basic_memory.services.sync_status_service import sync_status_tracker
+
+
+def _get_all_projects_status() -> list[str]:
+    """Get status lines for all configured projects."""
+    status_lines = []
+
+    try:
+        app_config = ConfigManager().config
+
+        if app_config.projects:
+            status_lines.extend(["", "---", "", "**All Projects Status:**"])
+
+            for project_name, project_path in app_config.projects.items():
+                # Check if this project has sync status
+                project_sync_status = sync_status_tracker.get_project_status(project_name)
+
+                if project_sync_status:
+                    # Project has tracked sync activity
+                    if project_sync_status.status.value == "watching":
+                        # Project is actively watching for changes (steady state)
+                        status_icon = "👁️"
+                        status_text = "Watching for changes"
+                    elif project_sync_status.status.value == "completed":
+                        # Sync completed but not yet watching - transitional state
+                        status_icon = "✅"
+                        status_text = "Sync completed"
+                    elif project_sync_status.status.value in ["scanning", "syncing"]:
+                        status_icon = "🔄"
+                        status_text = "Sync in progress"
+                        if project_sync_status.files_total > 0:
+                            progress_pct = (
+                                project_sync_status.files_processed
+                                / project_sync_status.files_total
+                            ) * 100
+                            status_text += f" ({project_sync_status.files_processed}/{project_sync_status.files_total}, {progress_pct:.0f}%)"
+                    elif project_sync_status.status.value == "failed":
+                        status_icon = "❌"
+                        status_text = f"Sync error: {project_sync_status.error or 'Unknown error'}"
+                    else:
+                        status_icon = "⏸️"
+                        status_text = project_sync_status.status.value.title()
+                else:
+                    # Project has no tracked sync activity - will be synced automatically
+                    status_icon = "⏳"
+                    status_text = "Pending sync"
+
+                status_lines.append(f"- {status_icon} **{project_name}**: {status_text}")
+
+    except Exception as e:
+        logger.debug(f"Could not get project config for comprehensive status: {e}")
+
+    return status_lines
+
+
+@mcp.tool(
+    description="""Check the status of file synchronization and background operations.
+    
+    Use this tool to:
+    - Check if file sync is in progress or completed
+    - Get detailed sync progress information  
+    - Understand if your files are fully indexed
+    - Get specific error details if sync operations failed
+    - Monitor initial project setup and legacy migration
+    
+    This covers all sync operations including:
+    - Initial project setup and file indexing
+    - Legacy project migration to unified database
+    - Ongoing file monitoring and updates
+    - Background processing of knowledge graphs
+    """,
+)
+async def sync_status(project: Optional[str] = None, context: Context | None = None) -> str:
+    """Get current sync status and system readiness information.
+
+    This tool provides detailed information about any ongoing or completed
+    sync operations, helping users understand when their files are ready.
+
+    Args:
+        project: Optional project name to get project-specific context
+
+    Returns:
+        Formatted sync status with progress, readiness, and guidance
+    """
+    logger.info("MCP tool call tool=sync_status")
+
+    status_lines = []
+
+    try:
+        from basic_memory.services.sync_status_service import sync_status_tracker
+
+        # Get overall summary
+        summary = sync_status_tracker.get_summary()
+        is_ready = sync_status_tracker.is_ready
+
+        # Header
+        status_lines.extend(
+            [
+                "# Basic Memory Sync Status",
+                "",
+                f"**Current Status**: {summary}",
+                f"**System Ready**: {'✅ Yes' if is_ready else '🔄 Processing'}",
+                "",
+            ]
+        )
+
+        if is_ready:
+            status_lines.extend(
+                [
+                    "✅ **All sync operations completed**",
+                    "",
+                    "- File indexing is complete",
+                    "- Knowledge graphs are up to date",
+                    "- All Basic Memory tools are fully operational",
+                    "",
+                    "Your knowledge base is ready for use!",
+                ]
+            )
+
+            # Show all projects status even when ready
+            status_lines.extend(_get_all_projects_status())
+        else:
+            # System is still processing - show both active and all projects
+            all_sync_projects = sync_status_tracker.get_all_projects()
+
+            active_projects = [
+                p for p in all_sync_projects.values() if p.status.value in ["scanning", "syncing"]
+            ]
+            failed_projects = [p for p in all_sync_projects.values() if p.status.value == "failed"]
+
+            if active_projects:
+                status_lines.extend(
+                    [
+                        "🔄 **File synchronization in progress**",
+                        "",
+                        "Basic Memory is automatically processing all configured projects and building knowledge graphs.",
+                        "This typically takes 1-3 minutes depending on the amount of content.",
+                        "",
+                        "**Currently Processing:**",
+                    ]
+                )
+
+                for project_status in active_projects:
+                    progress = ""
+                    if project_status.files_total > 0:
+                        progress_pct = (
+                            project_status.files_processed / project_status.files_total
+                        ) * 100
+                        progress = f" ({project_status.files_processed}/{project_status.files_total}, {progress_pct:.0f}%)"
+
+                    status_lines.append(
+                        f"- **{project_status.project_name}**: {project_status.message}{progress}"
+                    )
+
+                status_lines.extend(
+                    [
+                        "",
+                        "**What's happening:**",
+                        "- Scanning and indexing markdown files",
+                        "- Building entity and relationship graphs",
+                        "- Setting up full-text search indexes",
+                        "- Processing file changes and updates",
+                        "",
+                        "**What you can do:**",
+                        "- Wait for automatic processing to complete - no action needed",
+                        "- Use this tool again to check progress",
+                        "- Simple operations may work already",
+                        "- All projects will be available once sync finishes",
+                    ]
+                )
+
+            # Handle failed projects (independent of active projects)
+            if failed_projects:
+                status_lines.extend(["", "❌ **Some projects failed to sync:**", ""])
+
+                for project_status in failed_projects:
+                    status_lines.append(
+                        f"- **{project_status.project_name}**: {project_status.error or 'Unknown error'}"
+                    )
+
+                status_lines.extend(
+                    [
+                        "",
+                        "**Next steps:**",
+                        "1. Check the logs for detailed error information",
+                        "2. Ensure file permissions allow read/write access",
+                        "3. Try restarting the MCP server",
+                        "4. If issues persist, consider filing a support issue",
+                    ]
+                )
+            elif not active_projects:
+                # No active or failed projects - must be pending
+                status_lines.extend(
+                    [
+                        "⏳ **Sync operations pending**",
+                        "",
+                        "File synchronization has been queued but hasn't started yet.",
+                        "This usually resolves automatically within a few seconds.",
+                    ]
+                )
+
+        # Add comprehensive project status for all configured projects
+        all_projects_status = _get_all_projects_status()
+        if all_projects_status:
+            status_lines.extend(all_projects_status)
+
+            # Add explanation about automatic syncing if there are unsynced projects
+            unsynced_count = sum(1 for line in all_projects_status if "⏳" in line)
+            if unsynced_count > 0 and not is_ready:
+                status_lines.extend(
+                    [
+                        "",
+                        "**Note**: All configured projects will be automatically synced during startup.",
+                        "You don't need to manually switch projects - Basic Memory handles this for you.",
+                    ]
+                )
+
+        # Add project context if provided
+        if project:
+            try:
+                active_project = await get_active_project(client, project, context)
+                status_lines.extend(
+                    [
+                        "",
+                        "---",
+                        "",
+                        f"**Active Project**: {active_project.name}",
+                        f"**Project Path**: {active_project.home}",
+                    ]
+                )
+            except Exception as e:
+                logger.debug(f"Could not get project info: {e}")
+
+        return "\n".join(status_lines)
+
+    except Exception as e:
+        return f"""# Sync Status - Error
+
+❌ **Unable to check sync status**: {str(e)}
+
+**Troubleshooting:**
+- The system may still be starting up
+- Try waiting a few seconds and checking again  
+- Check logs for detailed error information
+- Consider restarting if the issue persists
+"""
--- a/Show More
+++ b/Show More