chore: update version to 0.17.7 for v0.17.7 release

Signed-off-by: Drew Cain <groksrc@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

.claude/commands/release/release.md

@@ -15,10 +15,16 @@ 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
-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
+
+#### 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
 
 #### Documentation Validation
 1. **Changelog Check**
@@ -39,19 +45,111 @@ 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
+- ✅ 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)
 
 ### Step 3: Monitor Release Process
-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`
+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
 
 ### Step 4: Post-Release Validation
-1. Verify GitHub release is created automatically
-2. Check PyPI publication
-3. Validate release assets
-4. Update any post-release documentation
+
+#### 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`
+
+#### MCP Registry Publication
+
+After PyPI release is published, update the MCP registry:
+
+1. **Verify PyPI Release**
+   - Confirm package is live: https://pypi.org/project/basic-memory/<version>/
+   - The `server.json` version was auto-updated by `just release`
+
+2. **Publish to MCP Registry**
+   ```bash
+   cd /Users/drew/code/basic-memory
+   mcp-publisher publish
+   ```
+
+   If not authenticated:
+   ```bash
+   mcp-publisher login github
+   # Follow device authentication flow
+   mcp-publisher publish
+   ```
+
+3. **Verify Publication**
+   ```bash
+   curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=basic-memory"
+   ```
+
+**Note:** The `mcp-publisher` CLI can be installed via Homebrew (`brew install mcp-publisher`) or from GitHub releases.
+
+#### 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
 
 ## Pre-conditions Check
 Before starting, verify:
@@ -74,19 +172,28 @@ 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
+🔌 MCP Registry: https://registry.modelcontextprotocol.io
 🚀 GitHub Actions: Completed
 
-Install with:
-uv tool install basic-memory
+Install with pip/uv:
+  uv tool install basic-memory
+
+Install with Homebrew:
+  brew install basicmachines-co/basic-memory/basic-memory
 
 Users can now upgrade:
-uv tool upgrade basic-memory
+  uv tool upgrade basic-memory
+  brew upgrade basic-memory
 ```
 
 ## Context
 - This creates production releases used by end users
 - Must pass all quality gates before proceeding
 - Uses the automated justfile target for consistency
-- Version is automatically updated in `__init__.py`
+- Version is automatically updated in `__init__.py` and `server.json`
 - Triggers automated GitHub release with changelog
-- Leverages uv-dynamic-versioning for package version management
+- Package is published to PyPI for `pip` and `uv` users
+- Homebrew formula is automatically updated for stable releases
+- MCP Registry is updated manually via `mcp-publisher publish`
+- Supports multiple installation methods (uv, pip, Homebrew)

.claude/commands/spec.md

@@ -0,0 +1,51 @@
+---
+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]
+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.
+
+Available commands:
+- `create [name]` - Create new specification
+- `status` - Show all spec statuses
+- `show [spec-name]` - Read a specific spec
+- `review [spec-name]` - Review implementation against spec
+
+## Your task
+
+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"
+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
+
+### If command is "show":
+1. Use mcp__basic-memory__read_note with project="specs"
+2. Display the full spec content
+
+### If command is "review":
+1. Read the specified spec and its "How to Evaluate" section
+2. Review current implementation against success criteria with careful evaluation of:
+   - **Functional completeness** - All specified features working
+   - **Test coverage analysis** - Actual test files and coverage percentage
+     - Count existing test files vs required components/APIs/composables
+     - Verify unit tests, integration tests, and end-to-end tests
+     - Check for missing test categories (component, API, workflow)
+   - **Code quality metrics** - TypeScript compilation, linting, performance
+   - **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
+5. If gaps found, clearly identify what still needs to be implemented/tested

.claude/commands/test-live.md

@@ -11,7 +11,7 @@ All test results are recorded as notes in a dedicated test project.
 **Parameters:**
 - `phase` (optional): Specific test phase to run (`recent`, `core`, `features`, `edge`, `workflows`, `stress`, or `all`)
 - `recent` - Focus on recent changes and new features (recommended for regular testing)
-- `core` - Essential tools only (Tier 1: write_note, read_note, search_notes, edit_note, list_projects, switch_project)
+- `core` - Essential tools only (Tier 1: write_note, read_note, search_notes, edit_note, list_memory_projects, recent_activity)
 - `features` - Core + important workflows (Tier 1 + Tier 2)
 - `all` - Comprehensive testing of all tools and scenarios
 
@@ -24,30 +24,66 @@ When the user runs `/project:test-live`, execute comprehensive test plan:
 
 ### **Tier 1: Critical Core (Always Test)**
 1. **write_note** - Foundation of all knowledge creation
-2. **read_note** - Primary knowledge retrieval mechanism  
+2. **read_note** - Primary knowledge retrieval mechanism
 3. **search_notes** - Essential for finding information
 4. **edit_note** - Core content modification capability
-5. **list_memory_projects** - Project discovery and status
-6. **switch_project** - Context switching for multi-project workflows
+5. **list_memory_projects** - Project discovery and session guidance
+6. **recent_activity** - Project discovery mode and activity analysis
 
 ### **Tier 2: Important Workflows (Usually Test)**
-7. **recent_activity** - Understanding what's changed
-8. **build_context** - Conversation continuity via memory:// URLs
-9. **create_memory_project** - Essential for project setup
-10. **move_note** - Knowledge organization
-11. **sync_status** - Understanding system state
+7. **build_context** - Conversation continuity via memory:// URLs
+8. **create_memory_project** - Essential for project setup
+9. **move_note** - Knowledge organization
+10. **sync_status** - Understanding system state
+11. **delete_project** - Project lifecycle management
 
 ### **Tier 3: Enhanced Functionality (Sometimes Test)**
 12. **view_note** - Claude Desktop artifact display
 13. **read_content** - Raw content access
 14. **delete_note** - Content removal
 15. **list_directory** - File system exploration
-16. **set_default_project** - Configuration
-17. **delete_project** - Administrative cleanup
+16. **edit_note** (advanced modes) - Complex find/replace operations
 
 ### **Tier 4: Specialized (Rarely Test)**
-18. **canvas** - Obsidian visualization (specialized use case)
-19. **MCP Prompts** - Enhanced UX tools (ai_assistant_guide, continue_conversation)
+17. **canvas** - Obsidian visualization (specialized use case)
+18. **MCP Prompts** - Enhanced UX tools (ai_assistant_guide, continue_conversation)
+
+## Stateless Architecture Testing
+
+### **Project Discovery Workflow (CRITICAL)**
+Test the new stateless project selection flow:
+
+1. **Initial Discovery**
+   - Call `list_memory_projects()` without knowing which project to use
+   - Verify clear session guidance appears: "Next: Ask which project to use"
+   - Confirm removal of CLI-specific references
+
+2. **Activity-Based Discovery**
+   - Call `recent_activity()` without project parameter (discovery mode)
+   - Verify intelligent project suggestions based on activity
+   - Test guidance: "Should I use [most-active-project] for this task?"
+
+3. **Session Tracking Validation**
+   - Verify all tool responses include `[Session: Using project 'name']`
+   - Confirm guidance reminds about session-wide project tracking
+
+4. **Single Project Constraint Mode**
+   - Test MCP server with `--project` parameter
+   - Verify all operations constrained to specified project
+   - Test project override behavior in constrained mode
+
+### **Explicit Project Parameters (CRITICAL)**
+All tools must require explicit project parameters:
+
+1. **Parameter Validation**
+   - Test all Tier 1 tools require `project` parameter
+   - Verify clear error messages for missing project
+   - Test invalid project name handling
+
+2. **No Session State Dependencies**
+   - Confirm no tool relies on "current project" concept
+   - Test rapid project switching within conversation
+   - Verify each call is truly independent
 
 ### Pre-Test Setup
 
@@ -72,7 +108,7 @@ Run the bash `date` command to get the current date/time.
    Purpose: Record all test observations and results
    ```
 
-Make sure to switch to the newly created project with the `switch_project()` tool.
+Make sure to use the newly created project for all subsequent test operations by specifying it in the `project` parameter of each tool call.
 
 4. **Baseline Documentation**
    Create initial test session note with:
@@ -143,46 +179,42 @@ Test essential MCP tools that form the foundation of Basic Memory:
 - ⚠️ Error scenarios (invalid operations)
 
 **5. list_memory_projects Tests (Critical):**
-- ✅ Display all projects with status indicators
-- ✅ Current and default project identification
+- ✅ Display all projects with clear session guidance
+- ✅ Project discovery workflow prompts
+- ✅ Removal of CLI-specific references
 - ✅ Empty project list handling
-- ✅ Project metadata accuracy
+- ✅ Single project constraint mode display
 
-**6. switch_project Tests (Critical):**
-- ✅ Switch between existing projects
-- ✅ Context preservation during switch
-- ⚠️ Invalid project name handling
-- ✅ Confirmation of successful switch
+**6. recent_activity Tests (Critical - Discovery Mode):**
+- ✅ Discovery mode without project parameter
+- ✅ Intelligent project suggestions based on activity
+- ✅ Guidance prompts for project selection
+- ✅ Session tracking reminders in responses
+- ⚠️ Performance with multiple projects
 
 ### Phase 2: Important Workflows (Tier 2 Tools)
 
-**7. recent_activity Tests (Important):**
-- ✅ Various timeframes ("today", "1 week", "1d")
-- ✅ Type filtering capabilities
-- ✅ Empty project scenarios
-- ⚠️ Performance with many recent changes
-
-**8. build_context Tests (Important):**
+**7. build_context Tests (Important):**
 - ✅ Different depth levels (1, 2, 3+)
 - ✅ Various timeframes for context
 - ✅ memory:// URL navigation
 - ⚠️ Performance with complex relation graphs
 
-**9. create_memory_project Tests (Important):**
+**8. create_memory_project Tests (Important):**
 - ✅ Create projects dynamically
 - ✅ Set default during creation
 - ✅ Path validation and creation
 - ⚠️ Invalid paths and names
 - ✅ Integration with existing projects
 
-**10. move_note Tests (Important):**
+**9. move_note Tests (Important):**
 - ✅ Move within same project
 - ✅ Cross-project moves with detection (#161)
 - ✅ Automatic folder creation
 - ✅ Database consistency validation
 - ⚠️ Special characters in paths
 
-**11. sync_status Tests (Important):**
+**10. sync_status Tests (Important):**
 - ✅ Background operation monitoring
 - ✅ File synchronization status
 - ✅ Project sync state reporting
@@ -190,36 +222,31 @@ Test essential MCP tools that form the foundation of Basic Memory:
 
 ### Phase 3: Enhanced Functionality (Tier 3 Tools)
 
-**12. view_note Tests (Enhanced):**
+**11. view_note Tests (Enhanced):**
 - ✅ Claude Desktop artifact display
 - ✅ Title extraction from frontmatter
 - ✅ Unicode and emoji content rendering
 - ⚠️ Error handling for non-existent notes
 
-**13. read_content Tests (Enhanced):**
+**12. read_content Tests (Enhanced):**
 - ✅ Raw file content access
 - ✅ Binary file handling
 - ✅ Image file reading
 - ⚠️ Large file performance
 
-**14. delete_note Tests (Enhanced):**
+**13. delete_note Tests (Enhanced):**
 - ✅ Single note deletion
 - ✅ Database consistency after deletion
 - ⚠️ Non-existent note handling
 - ✅ Confirmation of successful deletion
 
-**15. list_directory Tests (Enhanced):**
+**14. list_directory Tests (Enhanced):**
 - ✅ Directory content listing
 - ✅ Depth control and filtering
 - ✅ File name globbing
 - ⚠️ Empty directory handling
 
-**16. set_default_project Tests (Enhanced):**
-- ✅ Change default project
-- ✅ Configuration persistence
-- ⚠️ Invalid project handling
-
-**17. delete_project Tests (Enhanced):**
+**15. delete_project Tests (Enhanced):**
 - ✅ Project removal from config
 - ✅ Database cleanup
 - ⚠️ Default project protection
@@ -269,7 +296,7 @@ Test essential MCP tools that form the foundation of Basic Memory:
 1. Technical documentation project
 2. Personal recipe collection project
 3. Learning/course notes project
-4. Switch contexts during conversation
+4. Specify different projects for different operations
 5. Cross-reference related concepts
 
 **Content Evolution:**
@@ -281,13 +308,13 @@ Test essential MCP tools that form the foundation of Basic Memory:
 
 ### Phase 6: Specialized Tools Testing (Tier 4)
 
-**18. canvas Tests (Specialized):**
+**16. canvas Tests (Specialized):**
 - ✅ JSON Canvas generation
 - ✅ Node and edge creation
 - ✅ Obsidian compatibility
 - ⚠️ Complex graph handling
 
-**19. MCP Prompts Tests (Specialized):**
+**17. MCP Prompts Tests (Specialized):**
 - ✅ ai_assistant_guide output
 - ✅ continue_conversation functionality
 - ✅ Formatted search results
@@ -382,7 +409,7 @@ permalink: test-session-[phase]-[timestamp]
 ### 📊 Performance Metrics
 - Average write_note time: 0.3s
 - Search with 100+ notes: 0.6s
-- Project switch overhead: 0.1s
+- Project parameter overhead: <0.1s
 - Memory usage: [observed levels]
 
 ## Relations
@@ -402,7 +429,7 @@ permalink: test-session-[phase]-[timestamp]
 - Learning curve and intuitiveness
 
 **System Behavior:**
-- Context preservation across operations
+- Stateless operation independence
 - memory:// URL navigation reliability
 - Multi-step workflow cohesion
 - Edge case graceful handling

.claude/settings.json

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

.env.example

@@ -0,0 +1,28 @@
+# 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

.github/workflows/claude-code-review.yml

@@ -0,0 +1,83 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Only run for organization members and collaborators
+    if: |
+      github.event.pull_request.author_association == 'OWNER' ||
+      github.event.pull_request.author_association == 'MEMBER' ||
+      github.event.pull_request.author_association == 'COLLABORATOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          track_progress: true  # Enable visual progress tracking
+          allowed_bots: '*'
+          prompt: |
+            Review this Basic Memory PR against our team checklist:
+
+            ## Code Quality & Standards
+            - [ ] Follows Basic Memory's coding conventions in CLAUDE.md
+            - [ ] Python 3.12+ type annotations and async patterns
+            - [ ] SQLAlchemy 2.0 best practices
+            - [ ] FastAPI and Typer conventions followed
+            - [ ] 100-character line length limit maintained
+            - [ ] No commented-out code blocks
+
+            ## Testing & Documentation
+            - [ ] Unit tests for new functions/methods
+            - [ ] Integration tests for new MCP tools
+            - [ ] Test coverage for edge cases
+            - [ ] **100% test coverage maintained** (use `# pragma: no cover` only for truly hard-to-test code)
+            - [ ] Documentation updated (README, docstrings)
+            - [ ] CLAUDE.md updated if conventions change
+
+            ## Basic Memory Architecture
+            - [ ] MCP tools follow atomic, composable design
+            - [ ] Database changes include Alembic migrations
+            - [ ] Preserves local-first architecture principles
+            - [ ] Knowledge graph operations maintain consistency
+            - [ ] Markdown file handling preserves integrity
+            - [ ] AI-human collaboration patterns followed
+
+            ## Security & Performance
+            - [ ] No hardcoded secrets or credentials
+            - [ ] Input validation for MCP tools
+            - [ ] 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"'

.github/workflows/claude-issue-triage.yml

@@ -0,0 +1,71 @@
+name: Claude Issue Triage
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Issue Triage
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          track_progress: true  # Show triage progress
+          prompt: |
+            Analyze this new Basic Memory issue and perform triage:
+
+            **Issue Analysis:**
+            1. **Type Classification:**
+               - Bug report (code defect)
+               - Feature request (new functionality)
+               - Enhancement (improvement to existing feature)
+               - Documentation (docs improvement)
+               - Question/Support (user help)
+               - MCP tool issue (specific to MCP functionality)
+
+            2. **Priority Assessment:**
+               - Critical: Security issues, data loss, complete breakage
+               - High: Major functionality broken, affects many users
+               - Medium: Minor bugs, usability issues
+               - Low: Nice-to-have improvements, cosmetic issues
+
+            3. **Component Classification:**
+               - CLI commands
+               - MCP tools
+               - Database/sync
+               - Cloud functionality
+               - Documentation
+               - Testing
+
+            4. **Complexity Estimate:**
+               - Simple: Quick fix, documentation update
+               - Medium: Requires some investigation/testing
+               - Complex: Major feature work, architectural changes
+
+            **Actions to Take:**
+            1. Add appropriate labels using: `gh issue edit ${{ github.event.issue.number }} --add-label "label1,label2"`
+            2. Check for duplicates using: `gh search issues`
+            3. If duplicate found, comment mentioning the original issue
+            4. For feature requests, ask clarifying questions if needed
+            5. For bugs, request reproduction steps if missing
+
+            **Available Labels:**
+            - Type: bug, enhancement, feature, documentation, question, mcp-tool
+            - Priority: critical, high, medium, low
+            - Component: cli, mcp, database, cloud, docs, testing
+            - Complexity: simple, medium, complex
+            - Status: needs-reproduction, needs-clarification, duplicate
+
+            Read the issue carefully and provide helpful triage with appropriate labels.
+
+          claude_args: '--allowed-tools "Bash(gh issue:*),Bash(gh search:*),Read"'

.github/workflows/claude.yml

@@ -9,106 +9,60 @@ on:
     types: [opened, assigned]
   pull_request_review:
     types: [submitted]
+  pull_request_target:
+    types: [opened, synchronize]
 
 jobs:
   claude:
     if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
-      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
-
+      (
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+        (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) ||
+        (github.event_name == 'pull_request_target' && contains(github.event.pull_request.body, '@claude'))
+      ) && (
+        github.event.comment.author_association == 'OWNER' ||
+        github.event.comment.author_association == 'MEMBER' ||
+        github.event.comment.author_association == 'COLLABORATOR' ||
+        github.event.sender.author_association == 'OWNER' ||
+        github.event.sender.author_association == 'MEMBER' ||
+        github.event.sender.author_association == 'COLLABORATOR' ||
+        github.event.pull_request.author_association == 'OWNER' ||
+        github.event.pull_request.author_association == 'MEMBER' ||
+        github.event.pull_request.author_association == 'COLLABORATOR'
+      )
     runs-on: ubuntu-latest
     permissions:
       contents: read
       pull-requests: read
       issues: read
       id-token: write
+      actions: read # Required for Claude to read CI results on PRs
     steps:
-      - name: Check user permissions
-        id: check_membership
-        uses: actions/github-script@v7
-        with:
-          script: |
-            let actor;
-            if (context.eventName === 'issue_comment') {
-              actor = context.payload.comment.user.login;
-            } else if (context.eventName === 'pull_request_review_comment') {
-              actor = context.payload.comment.user.login;
-            } else if (context.eventName === 'pull_request_review') {
-              actor = context.payload.review.user.login;
-            } else if (context.eventName === 'issues') {
-              actor = context.payload.issue.user.login;
-            }
-            
-            console.log(`Checking permissions for user: ${actor}`);
-            
-            // List of explicitly allowed users (organization members)
-            const allowedUsers = [
-              'phernandez',
-              'groksrc',
-              'nellins',
-              'bm-claudeai'
-            ];
-            
-            if (allowedUsers.includes(actor)) {
-              console.log(`User ${actor} is in the allowed list`);
-              core.setOutput('is_member', true);
-              return;
-            }
-            
-            // Fallback: Check if user has repository permissions
-            try {
-              const collaboration = await github.rest.repos.getCollaboratorPermissionLevel({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                username: actor
-              });
-              
-              const permission = collaboration.data.permission;
-              console.log(`User ${actor} has permission level: ${permission}`);
-              
-              // Allow if user has push access or higher (write, maintain, admin)
-              const allowed = ['write', 'maintain', 'admin'].includes(permission);
-              
-              core.setOutput('is_member', allowed);
-              
-              if (!allowed) {
-                core.notice(`User ${actor} does not have sufficient repository permissions (has: ${permission})`);
-              }
-            } catch (error) {
-              console.log(`Error checking permissions: ${error.message}`);
-              
-              // Final fallback: Check if user is a public member of the organization
-              try {
-                const membership = await github.rest.orgs.getMembershipForUser({
-                  org: 'basicmachines-co',
-                  username: actor
-                });
-                
-                const allowed = membership.data.state === 'active';
-                core.setOutput('is_member', allowed);
-                
-                if (!allowed) {
-                  core.notice(`User ${actor} is not a public member of basicmachines-co organization`);
-                }
-              } catch (membershipError) {
-                console.log(`Error checking organization membership: ${membershipError.message}`);
-                core.setOutput('is_member', false);
-                core.notice(`User ${actor} does not have access to this repository`);
-              }
-            }
-
       - name: Checkout repository
-        if: steps.check_membership.outputs.is_member == 'true'
         uses: actions/checkout@v4
         with:
+          # For pull_request_target, checkout the PR head to review the actual changes
+          ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.sha || github.sha }}
           fetch-depth: 1
 
       - name: Run Claude Code
-        if: steps.check_membership.outputs.is_member == 'true'
         id: claude
-        uses: anthropics/claude-code-action@beta
+        uses: anthropics/claude-code-action@v1
         with:
-          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          allowed_tools: Bash(uv run pytest),Bash(uv run ruff check . --fix),Bash(uv run ruff format .),Bash(uv run pyright),Bash(just test),Bash(just lint),Bash(just format),Bash(just type-check),Bash(just check),Read,Write,Edit,MultiEdit,Glob,Grep,LS, mcp__web_search
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          track_progress: true  # Enable visual progress tracking
+          
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
+          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
+

.github/workflows/test.yml

@@ -13,12 +13,72 @@ on:
     branches: [ "main" ]
 
 jobs:
-  test:
-    runs-on: ubuntu-latest
+  test-sqlite:
+    name: Test SQLite (${{ matrix.os }}, Python ${{ matrix.python-version }})
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.12" ]
+        os: [ubuntu-latest, windows-latest]
+        python-version: [ "3.12", "3.13", "3.14" ]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install just (Linux/macOS)
+        if: runner.os != 'Windows'
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+
+      - name: Install just (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          # Install just using Chocolatey (pre-installed on GitHub Actions Windows runners)
+          choco install just --yes
+        shell: pwsh
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e .[dev]
+
+      - name: Run type checks
+        run: |
+          just typecheck
+
+      - name: Run linting
+        run: |
+          just lint
+
+      - name: Run tests (SQLite)
+        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", "3.14" ]
+    runs-on: ubuntu-latest
+
+    # Note: No services section needed - testcontainers handles Postgres in Docker
 
     steps:
       - uses: actions/checkout@v4
@@ -47,11 +107,61 @@ jobs:
         run: |
           uv pip install -e .[dev]
 
-      - name: Run type checks
-        run: |
-          just type-check
-
-      - name: Run tests
+      - name: Run tests (Postgres via testcontainers)
         run: |
           uv pip install pytest pytest-cov
-          just test
+          just test-postgres
+
+  coverage:
+    name: Coverage Summary (combined, Python 3.12)
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - 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 combined coverage (SQLite + Postgres)
+        run: |
+          uv pip install pytest pytest-cov
+          just coverage
+
+      - name: Add coverage report to job summary
+        if: always()
+        run: |
+          {
+            echo "## Coverage"
+            echo ""
+            echo '```'
+            uv run coverage report -m
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload HTML coverage report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: htmlcov
+          path: htmlcov/

.gitignore

@@ -52,4 +52,5 @@ ENV/
 
 # claude action
 claude-output
-**/.claude/settings.local.json
+**/.claude/settings.local.json
+.mcp.json

.python-version

@@ -1 +1 @@
-3.12
+3.14

CLA.md

@@ -1,34 +1,71 @@
-Developer Certificate of Origin
-Version 1.1
-https://developercertificate.org/
+# Contributor License Agreement
 
-Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+## Copyright Assignment and License Grant
 
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
+By signing this Contributor License Agreement ("Agreement"), you accept and agree to the following terms and conditions
+for your present and future Contributions submitted
+to Basic Machines LLC. Except for the license granted herein to Basic Machines LLC and recipients of software
+distributed by Basic Machines LLC, you reserve all right,
+title, and interest in and to your Contributions.
 
-Developer's Certificate of Origin 1.1
+### 1. Definitions
 
-By making a contribution to this project, I certify that:
+"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this
+Agreement with Basic Machines LLC.
 
-(a) The contribution was created in whole or in part by me and I
-have the right to submit it under the open source license
-indicated in the file; or
+"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work,
+that is intentionally submitted by You to Basic
+Machines LLC for inclusion in, or documentation of, any of the products owned or managed by Basic Machines LLC (the "
+Work").
 
-(b) The contribution is based upon previous work that, to the best
-of my knowledge, is covered under an appropriate open source
-license and I have the right under that license to submit that
-work with modifications, whether created in whole or in part
-by me, under the same open source license (unless I am
-permitted to submit under a different license), as indicated
-in the file; or
+### 2. Grant of Copyright License
 
-(c) The contribution was provided directly to me by some other
-person who certified (a), (b) or (c) and I have not modified
-it.
+Subject to the terms and conditions of this Agreement, You hereby grant to Basic Machines LLC and to recipients of
+software distributed by Basic Machines LLC a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the
+Work, and to permit persons to whom the Work is furnished to do so.
 
-(d) I understand and agree that this project and the contribution
-are public and that a record of the contribution (including all
-personal information I submit with it, including my sign-off) is
-maintained indefinitely and may be redistributed consistent with
-this project or the open source license(s) involved.
+### 3. Assignment of Copyright
+
+You hereby assign to Basic Machines LLC all right, title, and interest worldwide in all Copyright covering your
+Contributions. Basic Machines LLC may license the
+Contributions under any license terms, including copyleft, permissive, commercial, or proprietary licenses.
+
+### 4. Grant of Patent License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to Basic Machines LLC and to recipients of
+software distributed by Basic Machines LLC a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to
+make, have made, use, offer to sell, sell, import, and
+otherwise transfer the Work.
+
+### 5. Developer Certificate of Origin
+
+By making a Contribution to this project, You certify that:
+
+(a) The Contribution was created in whole or in part by You and You have the right to submit it under this Agreement; or
+
+(b) The Contribution is based upon previous work that, to the best of Your knowledge, is covered under an appropriate
+open source license and You have the right under that
+license to submit that work with modifications, whether created in whole or in part by You, under this Agreement; or
+
+(c) The Contribution was provided directly to You by some other person who certified (a), (b) or (c) and You have not
+modified it.
+
+(d) You understand and agree that this project and the Contribution are public and that a record of the Contribution (
+including all personal information You submit with
+it, including Your sign-off) is maintained indefinitely and may be redistributed consistent with this project or the
+open source license(s) involved.
+
+### 6. Representations
+
+You represent that you are legally entitled to grant the above license and assignment. If your employer(s) has rights to
+intellectual property that you create that
+includes your Contributions, you represent that you have received permission to make Contributions on behalf of that
+employer, or that your employer has waived such rights
+for your Contributions to Basic Machines LLC.
+
+---
+
+This Agreement is effective as of the date you first submit a Contribution to Basic Machines LLC.

CLAUDE.md

@@ -15,19 +15,39 @@ See the [README.md](README.md) file for a project overview.
 ### Build and Test Commands
 
 - Install: `just install` or `pip install -e ".[dev]"`
-- Run tests: `uv run pytest -p pytest_mock -v` or `just test`
+- Run all tests (SQLite + Postgres): `just test`
+- Run all tests against SQLite: `just test-sqlite`
+- Run all tests against Postgres: `just test-postgres` (uses testcontainers)
+- Run unit tests (SQLite): `just test-unit-sqlite`
+- Run unit tests (Postgres): `just test-unit-postgres`
+- Run integration tests (SQLite): `just test-int-sqlite`
+- Run integration tests (Postgres): `just test-int-postgres`
+- Generate HTML coverage: `just coverage`
 - Single test: `pytest tests/path/to/test_file.py::test_function_name`
+- Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`
 - Lint: `just lint` or `ruff check . --fix`
-- Type check: `just type-check` or `uv run pyright`
+- 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, type-check, test)
+- Run all code checks: `just check` (runs lint, format, typecheck, test)
 - Create db migration: `just migration "Your migration message"`
 - Run development MCP Inspector: `just run-inspector`
 
+**Note:** Project requires Python 3.12+ (uses type parameter syntax and `type` aliases introduced in 3.12)
+
+**Postgres Testing:** Uses [testcontainers](https://testcontainers-python.readthedocs.io/) which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.
+
+### Test Structure
+
+- `tests/` - Unit tests for individual components (mocked, fast)
+- `test-int/` - Integration tests for real-world scenarios (no mocks, realistic)
+- Both directories are covered by unified coverage reporting
+- Benchmark tests in `test-int/` are marked with `@pytest.mark.benchmark`
+- Slow tests are marked with `@pytest.mark.slow`
+
 ### Code Style Guidelines
 
 - Line length: 100 characters max
-- Python 3.12+ with full type annotations
+- Python 3.12+ with full type annotations (uses type parameters and type aliases)
 - Format with ruff (consistent styling)
 - Import order: standard lib, third-party, local imports
 - Naming: snake_case for functions/variables, PascalCase for classes
@@ -37,20 +57,98 @@ See the [README.md](README.md) file for a project overview.
 - API uses FastAPI for endpoints
 - Follow the repository pattern for data access
 - Tools communicate to api routers via the httpx ASGI client (in process)
-- avoid using "private" functions in modules or classes (prepended with _)
+
+### Code Change Guidelines
+
+- **Full file read before edits**: Before editing any file, read it in full first to ensure complete context; partial reads lead to corrupted edits
+- **Minimize diffs**: Prefer the smallest change that satisfies the request. Avoid unrelated refactors or style rewrites unless necessary for correctness
+- **No speculative getattr**: Never use `getattr(obj, "attr", default)` when unsure about attribute names. Check the class definition or source code first
+- **Fail fast**: Write code with fail-fast logic by default. Do not swallow exceptions with errors or warnings
+- **No fallback logic**: Do not add fallback logic unless explicitly told to and agreed with the user
+- **No guessing**: Do not say "The issue is..." before you actually know what the issue is. Investigate first.
+
+### Literate Programming Style
+
+Code should tell a story. Comments must explain the "why" and narrative flow, not just the "what".
+
+**Section Headers:**
+For files with multiple phases of logic, add section headers so the control flow reads like chapters:
+```python
+# --- Authentication ---
+# ... auth logic ...
+
+# --- Data Validation ---
+# ... validation logic ...
+
+# --- Business Logic ---
+# ... core logic ...
+```
+
+**Decision Point Comments:**
+For conditionals that materially change behavior (gates, fallbacks, retries, feature flags), add comments with:
+- **Trigger**: what condition causes this branch
+- **Why**: the rationale (cost, correctness, UX, determinism)
+- **Outcome**: what changes downstream
+
+```python
+# Trigger: project has no active sync watcher
+# Why: avoid duplicate file system watchers consuming resources
+# Outcome: starts new watcher, registers in active_watchers dict
+if project_id not in active_watchers:
+    start_watcher(project_id)
+```
+
+**Constraint Comments:**
+If code exists because of a constraint (async requirements, rate limits, schema compatibility), explain the constraint near the code:
+```python
+# SQLite requires WAL mode for concurrent read/write access
+connection.execute("PRAGMA journal_mode=WAL")
+```
+
+**What NOT to Comment:**
+Avoid comments that restate obvious code:
+```python
+# Bad - restates code
+counter += 1  # increment counter
+
+# Good - explains why
+counter += 1  # track retries for backoff calculation
+```
 
 ### Codebase Architecture
 
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture documentation.
+
+**Directory Structure:**
 - `/alembic` - Alembic db migrations
-- `/api` - FastAPI implementation of REST endpoints
-- `/cli` - Typer command-line interface
+- `/api` - FastAPI REST endpoints + `container.py` composition root
+- `/cli` - Typer CLI + `container.py` composition root
+- `/deps` - Feature-scoped FastAPI dependencies (config, db, projects, repositories, services, importers)
+- `/importers` - Import functionality for Claude, ChatGPT, and other sources
 - `/markdown` - Markdown parsing and processing
-- `/mcp` - Model Context Protocol server implementation
+- `/mcp` - MCP server + `container.py` composition root + `clients/` typed API clients
 - `/models` - SQLAlchemy ORM models
 - `/repository` - Data access layer
 - `/schemas` - Pydantic models for validation
 - `/services` - Business logic layer
-- `/sync` - File synchronization services
+- `/sync` - File synchronization services + `coordinator.py` for lifecycle management
+
+**Composition Roots:**
+Each entrypoint (API, MCP, CLI) has a composition root that:
+- Reads `ConfigManager` (the only place that reads global config)
+- Resolves runtime mode via `RuntimeMode` enum (TEST > CLOUD > LOCAL)
+- Provides dependencies to downstream code explicitly
+
+**Typed API Clients (MCP):**
+MCP tools use typed clients in `mcp/clients/` to communicate with the API:
+- `KnowledgeClient` - Entity CRUD operations
+- `SearchClient` - Search operations
+- `MemoryClient` - Context building
+- `DirectoryClient` - Directory listing
+- `ResourceClient` - Resource reading
+- `ProjectClient` - Project management
+
+Flow: MCP Tool → Typed Client → HTTP API → Router → Service → Repository
 
 ### Development Notes
 
@@ -62,10 +160,49 @@ 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)
-- Test database uses in-memory SQLite
-- Avoid creating mocks in tests in most circumstances.
-- Each test runs in a standalone environment with in memory SQLite and tmp_file directory
-- Do not use mocks in tests if possible. Tests run with an in memory sqlite db, so they are not needed. See fixtures in conftest.py
+- Unit tests (`tests/`) use mocks when necessary; integration tests (`test-int/`) use real implementations
+- By default, tests run against SQLite (fast, no Docker needed)
+- Set `BASIC_MEMORY_TEST_POSTGRES=1` to run against Postgres (uses testcontainers - Docker required)
+- Each test runs in a standalone environment with isolated database and tmp_path directory
+- CI runs SQLite and Postgres tests in parallel for faster feedback
+- Performance benchmarks are in `test-int/test_sync_performance_benchmark.py`
+- Use pytest markers: `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests
+- **Coverage must stay at 100%**: Write tests for new code. Only use `# pragma: no cover` when tests would require excessive mocking (e.g., TYPE_CHECKING blocks, error handlers that need failure injection, runtime-mode-dependent code paths)
+
+### Async Client Pattern (Important!)
+
+**All MCP tools and CLI commands use the context manager pattern for HTTP clients:**
+
+```python
+from basic_memory.mcp.async_client import get_client
+
+async def my_mcp_tool():
+    async with get_client() as client:
+        # Use client for API calls
+        response = await call_get(client, "/path")
+        return response
+```
+
+**Do NOT use:**
+- ❌ `from basic_memory.mcp.async_client import client` (deprecated module-level client)
+- ❌ Manual auth header management
+- ❌ `inject_auth_header()` (deleted)
+
+**Key principles:**
+- Auth happens at client creation, not per-request
+- Proper resource management via context managers
+- Supports three modes: Local (ASGI), CLI cloud (HTTP + auth), Cloud app (factory injection)
+- Factory pattern enables dependency injection for cloud consolidation
+
+**For cloud app integration:**
+```python
+from basic_memory.mcp import async_client
+
+# Set custom factory before importing tools
+async_client.set_client_factory(your_custom_factory)
+```
+
+See SPEC-16 for full context manager refactor details.
 
 ## BASIC MEMORY PRODUCT USAGE
 
@@ -82,14 +219,27 @@ See the [README.md](README.md) file for a project overview.
 
 ### Basic Memory Commands
 
-- Sync knowledge: `basic-memory sync` or `basic-memory sync --watch`
+**Local Commands:**
+- Check sync status: `basic-memory status`
 - Import from Claude: `basic-memory import claude conversations`
 - Import from ChatGPT: `basic-memory import chatgpt`
 - Import from Memory JSON: `basic-memory import memory-json`
-- Check sync status: `basic-memory status`
-- Tool access: `basic-memory tools` (provides CLI access to MCP tools)
-    - Guide: `basic-memory tools basic-memory-guide`
-    - Continue: `basic-memory tools continue-conversation --topic="search"`
+- Tool access: `basic-memory tool` (provides CLI access to MCP tools)
+    - Continue: `basic-memory tool continue-conversation --topic="search"`
+
+**Project Management:**
+- List projects: `basic-memory project list`
+- Add project: `basic-memory project add "name" ~/path`
+- Project info: `basic-memory project info`
+- One-way sync (local -> cloud): `basic-memory project sync`
+- Bidirectional sync: `basic-memory project bisync`
+- Integrity check: `basic-memory project check`
+
+**Cloud Commands (requires subscription):**
+- Authenticate: `basic-memory cloud login`
+- Logout: `basic-memory cloud logout`
+- Check cloud status: `basic-memory cloud status`
+- Setup cloud sync: `basic-memory cloud setup`
 
 ### MCP Capabilities
 
@@ -98,38 +248,65 @@ See the [README.md](README.md) file for a project overview.
   **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
-    - `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, section replace)
-    - `move_note(identifier, destination_path)` - Move notes with database consistency and search reindexing
-    - `view_note(identifier)` - Display notes as formatted artifacts for better readability in Claude Desktop
     - `read_content(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
-    - `delete_note(identifier)` - Delete notes from knowledge base
-
-  **Project Management:**
-    - `list_memory_projects()` - List all available projects with status indicators
-    - `switch_project(project_name)` - Switch to different project context during conversations
-    - `get_current_project()` - Show currently active project with statistics
-    - `create_memory_project(name, path, set_default)` - Create new Basic Memory projects
-    - `delete_project(name)` - Delete projects from configuration and database
-    - `set_default_project(name)` - Set default project in config
-    - `sync_status()` - Check file synchronization status and background operations
+    - `view_note(identifier, page, page_size)` - View notes as formatted artifacts for better readability
+    - `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, replace_section)
+    - `move_note(identifier, destination_path)` - Move notes to new locations, updating database and maintaining links
+    - `delete_note(identifier)` - Delete notes from the knowledge base
 
   **Knowledge Graph Navigation:**
     - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation continuity
     - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "1d", "1 week")
-    - `list_directory(dir_name, depth, file_name_glob)` - List directory contents with filtering and depth control
+    - `list_directory(dir_name, depth, file_name_glob)` - Browse directory contents with filtering and depth control
 
   **Search & Discovery:**
-    - `search_notes(query, page, page_size)` - Full-text search across all content with filtering options
+    - `search_notes(query, page, page_size, search_type, types, entity_types, after_date)` - Full-text search across all content with advanced filtering options
+
+  **Project Management:**
+    - `list_memory_projects()` - List all available projects with their status
+    - `create_memory_project(project_name, project_path, set_default)` - Create new Basic Memory projects
+    - `delete_project(project_name)` - Delete a project from configuration
 
   **Visualization:**
     - `canvas(nodes, edges, title, folder)` - Generate Obsidian canvas files for knowledge graph visualization
 
+  **ChatGPT-Compatible Tools:**
+    - `search(query)` - Search across knowledge base (OpenAI actions compatible)
+    - `fetch(id)` - Fetch full content of a search result document
+
 - MCP Prompts for better AI interaction:
     - `ai_assistant_guide()` - Guidance on effectively using Basic Memory tools for AI assistants
     - `continue_conversation(topic, timeframe)` - Continue previous conversations with relevant historical context
-    - `search_notes(query, after_date)` - Search with detailed, formatted results for better context understanding
+    - `search(query, after_date)` - Search with detailed, formatted results for better context understanding
     - `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
 
@@ -145,34 +322,37 @@ of using AI just for code generation, we've developed a true collaborative workf
 This approach has allowed us to tackle more complex challenges and build a more robust system than either humans or AI
 could achieve independently.
 
+**Problem-Solving Guidance:**
+- If a solution isn't working after reasonable effort, suggest alternative approaches
+- Don't persist with a problematic library or pattern when better alternatives exist
+- Example: When py-pglite caused cascading test failures, switching to testcontainers-postgres was the right call
+
 ## GitHub Integration
 
-Basic Memory uses Claude directly into the development workflow through GitHub:
+Basic Memory has taken AI-Human collaboration to the next level by integrating Claude directly into the development workflow through GitHub:
 
 ### GitHub MCP Tools
 
-Using the GitHub Model Context Protocol server, Claude can:
+Using the GitHub Model Context Protocol server, Claude can now:
 
 - **Repository Management**:
-    - View repository files and structure
-    - Read file contents
-    - Create new branches
-    - Create and update files
+  - View repository files and structure
+  - Read file contents
+  - Create new branches
+  - Create and update files
 
 - **Issue Management**:
-    - Create new issues
-    - Comment on existing issues
-    - Close and update issues
-    - Search across issues
+  - Create new issues
+  - Comment on existing issues
+  - Close and update issues
+  - Search across issues
 
 - **Pull Request Workflow**:
-    - Create pull requests
-    - Review code changes
-    - Add comments to PRs
+  - Create pull requests
+  - Review code changes
+  - Add comments to PRs
 
-This integration enables Claude to participate as a full team member in the development process, not just as a code
-generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic
-Machines organization with direct contributor access to the codebase.
+This integration enables Claude to participate as a full team member in the development process, not just as a code generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic Machines organization with direct contributor access to the codebase.
 
 ### Collaborative Development Process
 
@@ -182,76 +362,6 @@ With GitHub integration, the development workflow includes:
 2. **Contribution tracking** - All of Claude's contributions are properly attributed in the Git history
 3. **Branch management** - Claude can create feature branches for implementations
 4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
+5. **Code Commits**: ALWAYS sign off commits with `git commit -s`
 
-With this integration, the AI assistant is a full-fledged team member rather than just a tool for generating code
-snippets.
-
-
-### Basic Memory Pro
-
-Basic Memory Pro is a desktop GUI application that wraps the basic-memory CLI/MCP tools:
-
-- Built with Tauri (Rust), React (TypeScript), and a Python FastAPI sidecar
-- Provides visual knowledge graph exploration and project management
-- Uses the same core codebase but adds a desktop-friendly interface
-- Project configuration is shared between CLI and Pro versions
-- Multiple project support with visual switching interface
-
-local repo: /Users/phernandez/dev/basicmachines/basic-memory-pro
-github: https://github.com/basicmachines-co/basic-memory-pro
-
-## Release and Version Management
-
-Basic Memory uses `uv-dynamic-versioning` for automatic version management based on git tags:
-
-### Version Types
-- **Development versions**: Automatically generated from commits (e.g., `0.12.4.dev26+468a22f`)
-- **Beta releases**: Created by tagging with beta suffixes (e.g., `v0.13.0b1`, `v0.13.0rc1`)
-- **Stable releases**: Created by tagging with version numbers (e.g., `v0.13.0`)
-
-### Release Workflows
-
-#### Development Builds (Automatic)
-- Triggered on every push to `main` branch
-- Publishes dev versions like `0.12.4.dev26+468a22f` to PyPI
-- Allows continuous testing of latest changes
-- Users install with: `pip install basic-memory --pre --force-reinstall`
-
-#### Beta/RC Releases (Manual)
-- Create beta tag: `git tag v0.13.0b1 && git push origin v0.13.0b1`
-- Automatically builds and publishes to PyPI as pre-release
-- Users install with: `pip install basic-memory --pre`
-- Use for milestone testing before stable release
-
-#### Stable Releases (Automated)
-- Use the automated release system: `just release v0.13.0`
-- Includes comprehensive quality checks (lint, format, type-check, tests)
-- Automatically updates version in `__init__.py`
-- Creates git tag and pushes to GitHub
-- Triggers GitHub Actions workflow for:
-  - PyPI publication
-  - Homebrew formula update (requires HOMEBREW_TOKEN secret)
-
-**Manual method (legacy):**
-- Create version tag: `git tag v0.13.0 && git push origin v0.13.0`
-
-#### Homebrew Formula Updates
-- Automatically triggered after successful PyPI release for **stable releases only**
-- **Stable releases** (e.g., v0.13.7) automatically update the main `basic-memory` formula
-- **Pre-releases** (dev/beta/rc) are NOT automatically updated - users must specify version manually
-- Updates formula in `basicmachines-co/homebrew-basic-memory` repo
-- Requires `HOMEBREW_TOKEN` secret in GitHub repository settings:
-  - Create a fine-grained Personal Access Token with `Contents: Read and Write` and `Actions: Read` scopes on `basicmachines-co/homebrew-basic-memory`
-  - Add as repository secret named `HOMEBREW_TOKEN` in `basicmachines-co/basic-memory`
-- Formula updates include new version URL and SHA256 checksum
-
-### For Development
-- **Automated releases**: Use `just release v0.13.x` for stable releases and `just beta v0.13.0b1` for beta releases
-- **Quality gates**: All releases require passing lint, format, type-check, and test suites
-- **Version management**: Versions automatically derived from git tags via `uv-dynamic-versioning`
-- **Configuration**: `pyproject.toml` uses `dynamic = ["version"]`
-- **Release automation**: `__init__.py` updated automatically during release process
-- **CI/CD**: GitHub Actions handles building and PyPI publication
-
-## Development Notes
-- make sure you sign off on commits
+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.

CONTRIBUTING.md

@@ -27,13 +27,25 @@ project and how to get started as a developer.
 
    > **Note**: Basic Memory uses [just](https://just.systems) as a modern command runner. Install with `brew install just` or `cargo install just`.
 
-3. **Run the Tests**:
+3. **Activate the Virtual Environment**
    ```bash
-   # Run all tests
+   source .venv/bin/activate
+   ```
+
+4. **Run the Tests**:
+   ```bash
+   # Run all tests with unified coverage (unit + integration)
    just test
-   # or
-   uv run pytest -p pytest_mock -v
-   
+
+   # 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
+
    # Run a specific test
    pytest tests/path/to/test_file.py::test_function_name
    ```
@@ -129,7 +141,7 @@ agreement to the DCO.
 
 ## Code Style Guidelines
 
-- **Python Version**: Python 3.12+ with full type annotations
+- **Python Version**: Python 3.12+ with full type annotations (3.12+ required for type parameter syntax)
 - **Line Length**: 100 characters maximum
 - **Formatting**: Use ruff for consistent styling
 - **Import Order**: Standard lib, third-party, local imports
@@ -139,12 +151,78 @@ agreement to the DCO.
 
 ## Testing Guidelines
 
-- **Coverage Target**: We aim for 100% test coverage for all code
+### 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
 - **Test Framework**: Use pytest for unit and integration tests
-- **Mocking**: Use pytest-mock for mocking dependencies only when necessary
+- **Mocking**: Avoid mocking in integration tests; use sparingly in unit tests
 - **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
 

Dockerfile

@@ -1,26 +1,46 @@
 FROM python:3.12-slim-bookworm
 
+# Build arguments for user ID and group ID (defaults to 1000)
+ARG UID=1000
+ARG GID=1000
+
 # Copy uv from official image
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
 # Set environment variables
+# UV_PYTHON_INSTALL_DIR ensures Python is installed to a persistent location
+# that survives in the final image (not in /root/.local which gets lost)
+# UV_PYTHON_PREFERENCE=only-managed tells uv to use its managed Python version
 ENV PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1
+    PYTHONDONTWRITEBYTECODE=1 \
+    UV_PYTHON_INSTALL_DIR=/python \
+    UV_PYTHON_PREFERENCE=only-managed
+
+# Create a group and user with the provided UID/GID
+# Check if the GID already exists, if not create appgroup
+RUN (getent group ${GID} || groupadd --gid ${GID} appgroup) && \
+    useradd --uid ${UID} --gid ${GID} --create-home --shell /bin/bash appuser
 
 # Copy the project into the image
 ADD . /app
 
-# Sync the project into a new environment, asserting the lockfile is up to date
+# Install Python 3.13 explicitly and sync the project
 WORKDIR /app
-RUN uv sync --locked
+RUN uv python install 3.13
+RUN uv sync --locked --python 3.13
 
-# Create data directory
-RUN mkdir -p /app/data
+# Create necessary directories and set ownership
+RUN mkdir -p /app/data/basic-memory /app/.basic-memory && \
+    chown -R appuser:${GID} /app
 
 # Set default data directory and add venv to PATH
-ENV BASIC_MEMORY_HOME=/app/data \
+ENV BASIC_MEMORY_HOME=/app/data/basic-memory \
+    BASIC_MEMORY_PROJECT_ROOT=/app/data \
     PATH="/app/.venv/bin:$PATH"
 
+# Switch to the non-root user
+USER appuser
+
 # Expose port
 EXPOSE 8000
 
@@ -29,4 +49,4 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
     CMD basic-memory --version || exit 1
 
 # Use the basic-memory entrypoint to run the MCP server with default SSE transport
-CMD ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,3 +1,4 @@
+<!-- mcp-name: io.github.basicmachines-co/basic-memory -->
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![PyPI version](https://badge.fury.io/py/basic-memory.svg)](https://badge.fury.io/py/basic-memory)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
@@ -7,17 +8,24 @@
 ![](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
 Claude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to
 enable any compatible LLM to read and write to your local knowledge base.
 
-- Website: https://basicmemory.com
-- Company: https://basicmachines.co
+- Website: https://basicmachines.co
 - Documentation: https://memory.basicmachines.co
-- Discord: https://discord.gg/tyvKNccgqN
-- YouTube: https://www.youtube.com/@basicmachines-co
 
 ## Pick up your conversation right where you left off
 
@@ -33,10 +41,6 @@ https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc
 # Install with uv (recommended)
 uv tool install basic-memory
 
-# or with Homebrew
-brew tap basicmachines-co/basic-memory
-brew install basic-memory
-
 # Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)
 # Add this to your config:
 {
@@ -68,7 +72,8 @@ Memory for Claude Desktop:
 npx -y @smithery/cli install @basicmachines-co/basic-memory --client claude
 ```
 
-This installs and configures Basic Memory without requiring manual edits to the Claude Desktop configuration file. Note: The Smithery installation uses their hosted MCP server, while your data remains stored locally as Markdown files.
+This installs and configures Basic Memory without requiring manual edits to the Claude Desktop configuration file. The
+Smithery server hosts the MCP server component, while your data remains stored locally as Markdown files.
 
 ### Glama.ai
 
@@ -106,6 +111,9 @@ 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
 
@@ -159,8 +167,7 @@ The note embeds semantic content and links to other topics via simple Markdown f
 
 3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
 
-- Realtime sync is enabled by default starting with v0.12.0
-- Project switching during conversations is supported starting with v0.13.0
+- Realtime sync can be enabled via running `basic-memory sync --watch`
 
 4. In a chat with the LLM, you can reference a topic:
 
@@ -270,13 +277,6 @@ Examples of relations:
 ```
 
 ## Using with VS Code
-For one-click installation, click one of the install buttons below...
-
-[![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-UV-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22basic-memory%22%2C%22mcp%22%5D%7D) [![Install with UV in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UV-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22basic-memory%22%2C%22mcp%22%5D%7D&quality=insiders)
-
-You can use Basic Memory with VS Code to easily retrieve and store information while coding. Click the installation buttons above for one-click setup, or follow the manual installation instructions below.
-
-### Manual Installation
 
 Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
 
@@ -306,6 +306,8 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
 }
 ```
 
+You can use Basic Memory with VS Code to easily retrieve and store information while coding.
+
 ## Using with Claude Desktop
 
 Basic Memory is built using the MCP (Model Context Protocol) and works with the Claude desktop app (https://claude.ai/):
@@ -329,8 +331,7 @@ for OS X):
 }
 ```
 
-If you want to use a specific project (see [Multiple Projects](docs/User%20Guide.md#multiple-projects)), update your
-Claude Desktop
+If you want to use a specific project (see [Multiple Projects](#multiple-projects) below), update your Claude Desktop
 config:
 
 ```json
@@ -340,9 +341,9 @@ config:
       "command": "uvx",
       "args": [
         "basic-memory",
+        "mcp",
         "--project",
-        "your-project-name",
-        "mcp"
+        "your-project-name"
       ]
     }
   }
@@ -351,27 +352,66 @@ config:
 
 2. Sync your knowledge:
 
-Basic Memory will sync the files in your project in real time if you make manual edits.
+```bash
+# One-time sync of local knowledge updates
+basic-memory sync
 
-3. In Claude Desktop, the LLM can now use these tools:
+# Run realtime sync process (recommended)
+basic-memory sync --watch
+```
 
+3. Cloud features (optional, requires subscription):
+
+```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
-edit_note(identifier, operation, content) - Edit notes incrementally (append, prepend, find/replace)
+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
-view_note(identifier) - Display notes as formatted artifacts for better readability
+delete_note(identifier) - Delete notes from knowledge base
+```
+
+**Knowledge Graph Navigation:**
+```
 build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
-search_notes(query, page, page_size) - Search across your knowledge base
 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:**
+```
 canvas(nodes, edges, title, folder) - Generate knowledge visualizations
-list_memory_projects() - List all available projects with status
-switch_project(project_name) - Switch to different project context
-get_current_project() - Show current project and statistics
-create_memory_project(name, path, set_default) - Create new projects
-delete_project(name) - Delete projects from configuration
-set_default_project(name) - Set default project
-sync_status() - Check file synchronization status
 ```
 
 5. Example prompts to try:
@@ -382,63 +422,102 @@ sync_status() - Check file synchronization status
 "Create a canvas visualization of my project components"
 "Read my notes on the authentication system"
 "What have I been working on in the past week?"
-"Switch to my work-notes project"
-"List all my available projects"
-"Edit my coffee brewing note to add a new technique"
-"Move my old meeting notes to the archive folder"
 ```
 
 ## Futher info
 
 See the [Documentation](https://memory.basicmachines.co/) for more info, including:
 
-- [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)
+- [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)
 
-## Installation Options
+## Logging
 
-### Stable Release
-```bash
-pip install basic-memory
-```
+Basic Memory uses [Loguru](https://github.com/Delgan/loguru) for logging. The logging behavior varies by entry point:
 
-### Beta/Pre-releases
-```bash
-pip install basic-memory --pre
-```
+| Entry Point | Default Behavior | Use Case |
+|-------------|------------------|----------|
+| CLI commands | File only | Prevents log output from interfering with command output |
+| MCP server | File only | Stdout would corrupt the JSON-RPC protocol |
+| API server | File (local) or stdout (cloud) | Docker/cloud deployments use stdout |
 
-### Development Builds
-Development versions are automatically published on every commit to main with versions like `0.12.4.dev26+468a22f`:
-```bash
-pip install basic-memory --pre --force-reinstall
-```
+**Log file location:** `~/.basic-memory/basic-memory.log` (10MB rotation, 10 days retention)
 
-### Docker
+### Environment Variables
 
-Run Basic Memory in a container with volume mounting for your Obsidian vault:
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BASIC_MEMORY_LOG_LEVEL` | `INFO` | Log level: DEBUG, INFO, WARNING, ERROR |
+| `BASIC_MEMORY_CLOUD_MODE` | `false` | When `true`, API logs to stdout with structured context |
+| `BASIC_MEMORY_ENV` | `dev` | Set to `test` for test mode (stderr only) |
+
+### Examples
 
 ```bash
-# Clone and start with Docker Compose
-git clone https://github.com/basicmachines-co/basic-memory.git
-cd basic-memory
+# Enable debug logging
+BASIC_MEMORY_LOG_LEVEL=DEBUG basic-memory sync
 
-# Edit docker-compose.yml to point to your Obsidian vault
-# Then start the container
-docker-compose up -d
+# View logs
+tail -f ~/.basic-memory/basic-memory.log
+
+# Cloud/Docker mode (stdout logging with structured context)
+BASIC_MEMORY_CLOUD_MODE=true uvicorn basic_memory.api.app:app
 ```
 
-Or use Docker directly:
+## Development
+
+### Running Tests
+
+Basic Memory supports dual database backends (SQLite and Postgres). By default, tests run against SQLite. Set `BASIC_MEMORY_TEST_POSTGRES=1` to run against Postgres (uses testcontainers - Docker required).
+
+**Quick Start:**
 ```bash
-docker run -d \
-  --name basic-memory-server \
-  -v /path/to/your/obsidian-vault:/data/knowledge:rw \
-  -v basic-memory-config:/root/.basic-memory:rw \
-  ghcr.io/basicmachines-co/basic-memory:latest
+# Run all tests against SQLite (default, fast)
+just test-sqlite
+
+# Run all tests against Postgres (uses testcontainers)
+just test-postgres
+
+# Run both SQLite and Postgres tests
+just test
 ```
 
-See [Docker Setup Guide](docs/Docker.md) for detailed configuration options, multiple project setup, and integration examples.
+**Available Test Commands:**
+
+- `just test` - Run all tests against both SQLite and Postgres
+- `just test-sqlite` - Run all tests against SQLite (fast, no Docker needed)
+- `just test-postgres` - Run all tests against Postgres (uses testcontainers)
+- `just test-unit-sqlite` - Run unit tests against SQLite
+- `just test-unit-postgres` - Run unit tests against Postgres
+- `just test-int-sqlite` - Run integration tests against SQLite
+- `just test-int-postgres` - Run integration tests against Postgres
+- `just test-windows` - Run Windows-specific tests (auto-skips on other platforms)
+- `just test-benchmark` - Run performance benchmark tests
+
+**Postgres Testing:**
+
+Postgres tests use [testcontainers](https://testcontainers-python.readthedocs.io/) which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.
+
+**Test Markers:**
+
+Tests use pytest markers for selective execution:
+- `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.
 
 ## License
 

docker-compose-postgres.yml

@@ -0,0 +1,42 @@
+# 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

docs/AI Assistant Guide.md

@@ -1,431 +0,0 @@
----
-title: AI Assistant Guide
-type: note
-permalink: docs/ai-assistant-guide
----
-> Note: This is an optional document that can be copy/pasted into the project knowledge for an LLM to provide a full description of how it can work with Basic Memory. It is provided as a helpful resource. The tools contain extensive usage description prompts with enable the LLM to understand them. 
-
-You can [download](https://github.com/basicmachines-co/basic-memory/blob/main/docs/AI%20Assistant%20Guide.md) the contents of this file from GitHub
-# AI Assistant Guide for Basic Memory
-
-This guide helps you, the AI assistant, use Basic Memory tools effectively when working with users. It covers reading, writing, and navigating knowledge through the Model Context Protocol (MCP).
-
-## Quick Reference
-
-**Essential Tools:**
-- `write_note()` - Create/update notes (primary tool)
-- `read_note()` - Read existing content
-- `search_notes()` - Find information
-- `edit_note()` - Modify existing notes incrementally (v0.13.0)
-- `move_note()` - Organize files with database consistency (v0.13.0)
-
-**Project Management (v0.13.0):**
-- `list_projects()` - Show available projects
-- `switch_project()` - Change active project
-- `get_current_project()` - Current project info
-
-**Key Principles:**
-1. **Build connections** - Rich knowledge graphs > isolated notes
-2. **Ask permission** - "Would you like me to record this?"
-3. **Use exact titles** - For accurate `[[WikiLinks]]`
-4. **Leverage v0.13.0** - Edit incrementally, organize proactively, switch projects contextually
-
-## Overview
-
-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**: 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
-
-## The Importance of the Knowledge Graph
-
-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.
-
-When creating content, focus on:
-
-1. **Increasing Semantic Density**: Add multiple observations and relations to each note
-2. **Using Accurate References**: Aim to reference existing entities by their exact titles
-3. **Creating Forward References**: Feel free to reference entities that don't exist yet - Basic Memory will resolve these when they're created later
-4. **Creating Bidirectional Links**: When appropriate, connect entities from both directions
-5. **Using Meaningful Categories**: Add semantic context with appropriate observation categories
-6. **Choosing Precise Relations**: Use specific relation types that convey meaning
-
-Remember that 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
-
-### Essential Content Management
-
-**Writing knowledge** (most important tool):
-```
-write_note(
-    title="Search Design",
-    content="# Search Design\n...",
-    folder="specs",                     # Optional
-    tags=["search", "design"],          # v0.13.0: now searchable!
-    project="work-notes"                # v0.13.0: target specific project
-)
-```
-
-**Reading knowledge:**
-```
-read_note("Search Design")              # By title
-read_note("specs/search-design")        # By path
-read_note("memory://specs/search")      # By memory URL
-```
-
-**Viewing notes as formatted artifacts (Claude Desktop):**
-```
-view_note("Search Design")              # Creates readable artifact
-view_note("specs/search-design")        # By permalink
-view_note("memory://specs/search")      # By memory URL
-```
-
-**Incremental editing** (v0.13.0):
-```
-edit_note(
-    identifier="Search Design",         # Must be EXACT title/permalink (strict matching)
-    operation="append",                 # append, prepend, find_replace, replace_section
-    content="\n## New Section\nContent here..."
-)
-```
-**⚠️ Important:** `edit_note` requires exact identifiers (no fuzzy matching). Use `search_notes()` first if uncertain.
-
-**File organization** (v0.13.0):
-```
-move_note(
-    identifier="Old Note",              # Must be EXACT title/permalink (strict matching)
-    destination="archive/old-note.md"   # Folders created automatically
-)
-```
-**⚠️ Important:** `move_note` requires exact identifiers (no fuzzy matching). Use `search_notes()` first if uncertain.
-
-### Project Management (v0.13.0)
-
-```
-list_projects()                         # Show available projects
-switch_project("work-notes")            # Change active project
-get_current_project()                   # Current project info
-```
-
-### Search & Discovery
-
-```
-search_notes("authentication system")   # v0.13.0: includes frontmatter tags
-build_context("memory://specs/search")  # Follow knowledge graph connections
-recent_activity(timeframe="1 week")     # Check what's been updated
-```
-
-## 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.
-   [Use write_note() to record the conversation details]
-   ```
-
-2. **Referencing existing knowledge**:
-   ```
-   Human: "Take a look at memory://specs/search"
-   
-   You: I'll examine that information.
-   [Use build_context() to gather related information]
-   [Then read_note() to access specific content]
-   ```
-
-3. **Finding information**:
-   ```
-   Human: "What were our decisions about auth?"
-   
-   You: Let me find that information for you.
-   [Use search_notes() to find relevant notes]
-   [Then build_context() to understand connections]
-   ```
-
-4. **Editing existing notes (v0.13.0)**:
-   ```
-   Human: "Add a section about deployment to my API documentation"
-   
-   You: I'll add that section to your existing documentation.
-   [Use edit_note() with operation="append" to add new content]
-   ```
-
-5. **Project management (v0.13.0)**:
-   ```
-   Human: "Switch to my work project and show recent activity"
-   
-   You: I'll switch to your work project and check what's been updated recently.
-   [Use switch_project() then recent_activity()]
-   ```
-
-6. **File organization (v0.13.0)**:
-   ```
-   Human: "Move my old meeting notes to the archive folder"
-   
-   You: I'll organize those notes for you.
-   [Use move_note() to relocate files with database consistency]
-   ```
-
-## 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**
-   - Same title+folder overwrites existing notes
-   - Structure with clear headings and semantic markup
-   - Use tags for searchability (v0.13.0: frontmatter tags indexed)
-   - Keep files organized in logical folders
-
-4. **Leverage v0.13.0 Features**
-   - **Edit incrementally**: Use `edit_note()` for small changes vs rewriting
-   - **Switch projects**: Change context when user mentions different work areas
-   - **Organize proactively**: Move old content to archive folders
-   - **Cross-project operations**: Create notes in specific projects while maintaining context
-
-## Common Knowledge Patterns
-
-### Capturing Decisions
-
-```markdown
----
-title: Coffee Brewing Methods
-tags: [coffee, brewing, pour-over, techniques]  # v0.13.0: Now searchable!
----
-
-# 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
-- [timing] Total brew time of 3-4 minutes produces optimal extraction #process
-
-## Relations
-- pairs_with [[Light Roast Beans]]
-- contrasts_with [[French Press Method]]
-- requires [[Proper Grinding Technique]]
-- part_of [[Morning Coffee Routine]]
-```
-
-### 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]]
-```
-
-## v0.13.0 Workflow Examples
-
-### Multi-Project Conversations
-
-**User:** "I need to update my work documentation and also add a personal recipe note."
-
-**Workflow:**
-1. `list_projects()` - Check available projects
-2. `write_note(title="Sprint Planning", project="work-notes")` - Work content
-3. `write_note(title="Weekend Recipes", project="personal")` - Personal content
-
-### Incremental Note Building
-
-**User:** "Add a troubleshooting section to my setup guide."
-
-**Workflow:**
-1. `edit_note(identifier="Setup Guide", operation="append", content="\n## Troubleshooting\n...")`
-
-**User:** "Update the authentication section in my API docs."
-
-**Workflow:**
-1. `edit_note(identifier="API Documentation", operation="replace_section", section="## Authentication")`
-
-### Smart File Organization
-
-**User:** "My notes are getting messy in the main folder."
-
-**Workflow:**
-1. `move_note("Old Meeting Notes", "archive/2024/old-meetings.md")`
-2. `move_note("Project Notes", "projects/client-work/notes.md")`
-
-### Creating Effective Relations
-
-When creating relations:
-1. **Reference existing entities** by their exact title: `[[Exact Title]]`
-2. **Create forward references** to entities that don't exist yet - they'll be linked automatically when created
-3. **Search first** to find existing entities to reference
-4. **Use meaningful relation types**: `implements`, `requires`, `part_of` vs generic `relates_to`
-
-**Example workflow:**
-1. `search_notes("travel")` to find existing travel-related notes
-2. Reference found entities: `- part_of [[Japan Travel Guide]]`
-3. Add forward references: `- located_in [[Tokyo]]` (even if Tokyo note doesn't exist yet)
-
-## Common Issues & Solutions
-
-**Missing Content:**
-- Try `search_notes()` with broader terms if `read_note()` fails
-- Use fuzzy matching: search for partial titles
-
-**Forward References:**
-- These are normal! Basic Memory links them automatically when target notes are created
-- Inform users: "I've created forward references that will be linked when you create those notes"
-
-**Sync Issues:**
-- If information seems outdated, suggest `basic-memory sync`
-- Use `recent_activity()` to check if content is current
-
-**Strict Mode for Edit/Move Operations:**
-- `edit_note()` and `move_note()` require **exact identifiers** (no fuzzy matching for safety)
-- If identifier not found: use `search_notes()` first to find the exact title/permalink
-- Error messages will guide you to find correct identifiers
-- Example workflow:
-  ```
-  # ❌ This might fail if identifier isn't exact
-  edit_note("Meeting Note", "append", "content")
-  
-  # ✅ Safe approach: search first, then use exact result
-  results = search_notes("meeting")
-  edit_note("Meeting Notes 2024", "append", "content")  # Use exact title from search
-  ```
-
-## Best Practices
-
-1. **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"
-
-2. **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
-
-3. **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
-
-4. **Navigate Knowledge Effectively**
-   - Start with specific searches
-   - Follow relation paths
-   - Combine information from multiple sources
-   - Verify information is current
-   - Build a complete picture before responding
-
-5. **Help Users Maintain Their Knowledge**
-   - Suggest organizing related topics
-   - Identify potential duplicates
-   - 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?"
-
-
-Built with ♥️ by Basic Machines

docs/ARCHITECTURE.md

@@ -0,0 +1,412 @@
+# Basic Memory Architecture
+
+This document describes the architectural patterns and composition structure of Basic Memory.
+
+## Overview
+
+Basic Memory is a local-first knowledge management system with three entrypoints:
+- **API** - FastAPI REST server for HTTP access
+- **MCP** - Model Context Protocol server for LLM integration
+- **CLI** - Typer command-line interface
+
+Each entrypoint uses a **composition root** pattern to manage configuration and dependencies.
+
+## Composition Roots
+
+### What is a Composition Root?
+
+A composition root is the single place in an application where dependencies are wired together. In Basic Memory, each entrypoint has its own composition root that:
+
+1. Reads configuration from `ConfigManager`
+2. Resolves runtime mode (cloud/local/test)
+3. Creates and provides dependencies to downstream code
+
+**Key principle**: Only composition roots read global configuration. All other modules receive configuration explicitly.
+
+### Container Structure
+
+Each entrypoint has a container dataclass in its package:
+
+```
+src/basic_memory/
+├── api/
+│   └── container.py      # ApiContainer
+├── mcp/
+│   └── container.py      # McpContainer
+├── cli/
+│   └── container.py      # CliContainer
+└── runtime.py            # RuntimeMode enum and resolver
+```
+
+### Container Pattern
+
+All containers follow the same structure:
+
+```python
+@dataclass
+class Container:
+    config: BasicMemoryConfig
+    mode: RuntimeMode
+
+    @classmethod
+    def create(cls) -> "Container":
+        """Create container by reading ConfigManager."""
+        config = ConfigManager().config
+        mode = resolve_runtime_mode(
+            cloud_mode_enabled=config.cloud_mode_enabled,
+            is_test_env=config.is_test_env,
+        )
+        return cls(config=config, mode=mode)
+
+    @property
+    def some_computed_property(self) -> bool:
+        """Derived values based on config and mode."""
+        return self.mode.is_local and self.config.some_setting
+
+# Module-level singleton
+_container: Container | None = None
+
+def get_container() -> Container:
+    if _container is None:
+        raise RuntimeError("Container not initialized")
+    return _container
+
+def set_container(container: Container) -> None:
+    global _container
+    _container = container
+```
+
+### Runtime Mode Resolution
+
+The `RuntimeMode` enum centralizes mode detection:
+
+```python
+class RuntimeMode(Enum):
+    LOCAL = "local"
+    CLOUD = "cloud"
+    TEST = "test"
+
+    @property
+    def is_cloud(self) -> bool:
+        return self == RuntimeMode.CLOUD
+
+    @property
+    def is_local(self) -> bool:
+        return self == RuntimeMode.LOCAL
+
+    @property
+    def is_test(self) -> bool:
+        return self == RuntimeMode.TEST
+```
+
+Resolution follows this precedence: **TEST > CLOUD > LOCAL**
+
+```python
+def resolve_runtime_mode(cloud_mode_enabled: bool, is_test_env: bool) -> RuntimeMode:
+    if is_test_env:
+        return RuntimeMode.TEST
+    if cloud_mode_enabled:
+        return RuntimeMode.CLOUD
+    return RuntimeMode.LOCAL
+```
+
+## Dependencies Package
+
+### Structure
+
+The `deps/` package provides FastAPI dependencies organized by feature:
+
+```
+src/basic_memory/deps/
+├── __init__.py       # Re-exports for backwards compatibility
+├── config.py         # Configuration access
+├── db.py             # Database/session management
+├── projects.py       # Project resolution
+├── repositories.py   # Data access layer
+├── services.py       # Business logic layer
+└── importers.py      # Import functionality
+```
+
+### Usage in Routers
+
+```python
+from basic_memory.deps.services import get_entity_service
+from basic_memory.deps.projects import get_project_config
+
+@router.get("/entities/{id}")
+async def get_entity(
+    id: int,
+    entity_service: EntityService = Depends(get_entity_service),
+    project: ProjectConfig = Depends(get_project_config),
+):
+    return await entity_service.get(id)
+```
+
+### Backwards Compatibility
+
+The old `deps.py` file still exists as a thin re-export shim:
+
+```python
+# deps.py - backwards compatibility shim
+from basic_memory.deps import *
+```
+
+New code should import from specific submodules (`basic_memory.deps.services`) for clarity.
+
+## MCP Tools Architecture
+
+### Typed API Clients
+
+MCP tools communicate with the API through typed clients that encapsulate HTTP paths and response validation:
+
+```
+src/basic_memory/mcp/clients/
+├── __init__.py       # Re-exports all clients
+├── base.py           # BaseClient with common logic
+├── knowledge.py      # KnowledgeClient - entity CRUD
+├── search.py         # SearchClient - search operations
+├── memory.py         # MemoryClient - context building
+├── directory.py      # DirectoryClient - directory listing
+├── resource.py       # ResourceClient - resource reading
+└── project.py        # ProjectClient - project management
+```
+
+### Client Pattern
+
+Each client encapsulates API paths and validates responses:
+
+```python
+class KnowledgeClient(BaseClient):
+    """Client for knowledge/entity operations."""
+
+    async def resolve_entity(self, identifier: str) -> int:
+        """Resolve identifier to entity ID."""
+        response = await call_get(
+            self.http_client,
+            f"{self._base_path}/resolve/{identifier}",
+        )
+        return int(response.text)
+
+    async def get_entity(self, entity_id: int) -> EntityResponse:
+        """Get entity by ID."""
+        response = await call_get(
+            self.http_client,
+            f"{self._base_path}/entities/{entity_id}",
+        )
+        return EntityResponse.model_validate(response.json())
+```
+
+### Tool → Client → API Flow
+
+```
+MCP Tool (thin adapter)
+    ↓
+Typed Client (encapsulates paths, validates responses)
+    ↓
+HTTP API (FastAPI router)
+    ↓
+Service Layer (business logic)
+    ↓
+Repository Layer (data access)
+```
+
+Example tool using typed client:
+
+```python
+@mcp.tool()
+async def search_notes(query: str, project: str | None = None) -> SearchResponse:
+    async with get_client() as client:
+        active_project = await get_active_project(client, project)
+
+        # Import client inside function to avoid circular imports
+        from basic_memory.mcp.clients import SearchClient
+
+        search_client = SearchClient(client, active_project.external_id)
+        return await search_client.search(query)
+```
+
+## Sync Coordination
+
+### SyncCoordinator
+
+The `SyncCoordinator` centralizes sync/watch lifecycle management:
+
+```python
+@dataclass
+class SyncCoordinator:
+    """Coordinates file sync and watch operations."""
+
+    status: SyncStatus = SyncStatus.NOT_STARTED
+    sync_task: asyncio.Task | None = None
+    watch_service: WatchService | None = None
+
+    async def start(self, ...):
+        """Start sync and watch operations."""
+
+    async def stop(self):
+        """Stop all sync operations gracefully."""
+
+    def get_status_info(self) -> dict:
+        """Get current sync status for observability."""
+```
+
+### Status Enum
+
+```python
+class SyncStatus(Enum):
+    NOT_STARTED = "not_started"
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    ERROR = "error"
+```
+
+## Project Resolution
+
+### ProjectResolver
+
+Unified project selection across all entrypoints:
+
+```python
+class ProjectResolver:
+    """Resolves which project to use based on context."""
+
+    def resolve(
+        self,
+        explicit_project: str | None = None,
+    ) -> ResolvedProject:
+        """Resolve project using three-tier hierarchy:
+        1. Explicit project parameter
+        2. Default project from config
+        3. Single available project
+        """
+```
+
+### Resolution Modes
+
+```python
+class ResolutionMode(Enum):
+    EXPLICIT = "explicit"           # User specified project
+    DEFAULT = "default"             # Using configured default
+    SINGLE_PROJECT = "single"       # Only one project exists
+    FALLBACK = "fallback"           # Using first available
+```
+
+## Testing Patterns
+
+### Container Testing
+
+Each container has corresponding tests:
+
+```
+tests/
+├── api/test_api_container.py
+├── mcp/test_mcp_container.py
+└── cli/test_cli_container.py
+```
+
+Tests verify:
+- Container creation from config
+- Runtime mode properties
+- Container accessor functions (get/set)
+
+### Mocking Typed Clients
+
+When testing MCP tools, mock at the client level:
+
+```python
+def test_search_notes(monkeypatch):
+    import basic_memory.mcp.clients as clients_mod
+
+    class MockSearchClient:
+        async def search(self, query):
+            return SearchResponse(results=[...])
+
+    monkeypatch.setattr(clients_mod, "SearchClient", MockSearchClient)
+```
+
+## Design Principles
+
+### 1. Explicit Dependencies
+
+Modules receive configuration explicitly rather than reading globals:
+
+```python
+# Good - explicit injection
+async def sync_files(config: BasicMemoryConfig):
+    ...
+
+# Avoid - hidden global access
+async def sync_files():
+    config = ConfigManager().config  # Hidden coupling
+```
+
+### 2. Single Responsibility
+
+Each layer has a clear responsibility:
+- **Containers**: Wire dependencies
+- **Clients**: Encapsulate HTTP communication
+- **Services**: Business logic
+- **Repositories**: Data access
+- **Tools/Routers**: Thin adapters
+
+### 3. Deferred Imports
+
+To avoid circular imports, typed clients are imported inside functions:
+
+```python
+async def my_tool():
+    async with get_client() as client:
+        # Import here to avoid circular dependency
+        from basic_memory.mcp.clients import KnowledgeClient
+
+        knowledge_client = KnowledgeClient(client, project_id)
+```
+
+### 4. Backwards Compatibility
+
+When refactoring, maintain backwards compatibility via shims:
+
+```python
+# Old module becomes a shim
+from basic_memory.new_location import *
+
+# Docstring explains migration path
+"""
+DEPRECATED: Import from basic_memory.new_location instead.
+This shim will be removed in a future version.
+"""
+```
+
+## File Organization
+
+```
+src/basic_memory/
+├── api/
+│   ├── container.py          # API composition root
+│   ├── routers/              # FastAPI routers
+│   └── ...
+├── mcp/
+│   ├── container.py          # MCP composition root
+│   ├── clients/              # Typed API clients
+│   ├── tools/                # MCP tool definitions
+│   └── server.py             # MCP server setup
+├── cli/
+│   ├── container.py          # CLI composition root
+│   ├── app.py                # Typer app
+│   └── commands/             # CLI command groups
+├── deps/
+│   ├── config.py             # Config dependencies
+│   ├── db.py                 # Database dependencies
+│   ├── projects.py           # Project dependencies
+│   ├── repositories.py       # Repository dependencies
+│   ├── services.py           # Service dependencies
+│   └── importers.py          # Importer dependencies
+├── sync/
+│   ├── coordinator.py        # SyncCoordinator
+│   └── ...
+├── runtime.py                # RuntimeMode resolution
+├── project_resolver.py       # Unified project selection
+└── config.py                 # Configuration management
+```

docs/Docker.md

@@ -15,7 +15,7 @@ Basic Memory provides pre-built Docker images on GitHub Container Registry that
      --name basic-memory-server \
      -p 8000:8000 \
      -v /path/to/your/obsidian-vault:/app/data:rw \
-     -v basic-memory-config:/root/.basic-memory:rw \
+     -v basic-memory-config:/app/.basic-memory:rw \
      ghcr.io/basicmachines-co/basic-memory:latest
    ```
 
@@ -30,7 +30,7 @@ Basic Memory provides pre-built Docker images on GitHub Container Registry that
          - "8000:8000"
        volumes:
          - /path/to/your/obsidian-vault:/app/data:rw
-         - basic-memory-config:/root/.basic-memory:rw
+         - basic-memory-config:/app/.basic-memory:rw
        environment:
          - BASIC_MEMORY_DEFAULT_PROJECT=main
        restart: unless-stopped
@@ -67,7 +67,7 @@ docker build -t basic-memory .
 docker run -d \
   --name basic-memory-server \
   -v /path/to/your/obsidian-vault:/app/data:rw \
-  -v basic-memory-config:/root/.basic-memory:rw \
+  -v basic-memory-config:/app/.basic-memory:rw \
   -e BASIC_MEMORY_DEFAULT_PROJECT=main \
   basic-memory
 ```
@@ -86,11 +86,11 @@ Basic Memory requires several volume mounts for proper operation:
 
 2. **Configuration and Database** (Recommended):
    ```yaml
-   - basic-memory-config:/root/.basic-memory:rw
+   - basic-memory-config:/app/.basic-memory:rw
    ```
    Persistent storage for configuration and SQLite database.
 
-You can edit the basic-memory config.json file located in the /root/.basic-memory/config.json after Basic Memory starts.
+You can edit the basic-memory config.json file located in the /app/.basic-memory/config.json after Basic Memory starts.
 
 3. **Multiple Projects** (Optional):
    ```yaml
@@ -98,7 +98,7 @@ You can edit the basic-memory config.json file located in the /root/.basic-memor
    - /path/to/project2:/app/data/project2:rw
    ```
 
-You can edit the basic-memory config.json file located in the /root/.basic-memory/config.json
+You can edit the basic-memory config.json file located in the /app/.basic-memory/config.json
 
 ## CLI Commands via Docker
 
@@ -123,7 +123,7 @@ When using Docker volumes, you'll need to configure projects to point to your mo
 
 1. **Check current configuration:**
    ```bash
-   docker exec basic-memory-server cat /root/.basic-memory/config.json
+   docker exec basic-memory-server cat /app/.basic-memory/config.json
    ```
 
 2. **Add a project for your mounted volume:**
@@ -184,16 +184,47 @@ environment:
 
 ### Linux/macOS
 
-Ensure your knowledge directories have proper permissions:
+The Docker container now runs as a non-root user to avoid file ownership issues. By default, the container uses UID/GID 1000, but you can customize this to match your user:
 
 ```bash
-# Make directories readable/writable
-chmod -R 755 /path/to/your/obsidian-vault
+# Build with custom UID/GID to match your user
+docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t basic-memory .
 
-# If using specific user/group
-chown -R $USER:$USER /path/to/your/obsidian-vault
+# Or use docker-compose with build args
 ```
 
+**Example docker-compose.yml with custom user:**
+```yaml
+version: '3.8'
+services:
+  basic-memory:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        UID: 1000  # Replace with your UID
+        GID: 1000  # Replace with your GID
+    container_name: basic-memory-server
+    ports:
+      - "8000:8000"
+    volumes:
+      - /path/to/your/obsidian-vault:/app/data:rw
+      - basic-memory-config:/app/.basic-memory:rw
+    environment:
+      - BASIC_MEMORY_DEFAULT_PROJECT=main
+    restart: unless-stopped
+```
+
+**Using pre-built images:**
+If using the pre-built image from GitHub Container Registry, files will be created with UID/GID 1000. You can either:
+
+1. Change your local directory ownership to match:
+   ```bash
+   sudo chown -R 1000:1000 /path/to/your/obsidian-vault
+   ```
+
+2. Or build your own image with custom UID/GID as shown above.
+
 ### Windows
 
 When using Docker Desktop on Windows, ensure the directories are shared:
@@ -217,7 +248,7 @@ When using Docker Desktop on Windows, ensure the directories are shared:
       ```
 
 2. **Configuration Not Persisting:**
-    - Use named volumes for `/root/.basic-memory`
+    - Use named volumes for `/app/.basic-memory`
     - Check volume mount permissions
 
 3. **Network Connectivity:**
@@ -243,10 +274,10 @@ docker-compose logs -f basic-memory
 ## Security Considerations
 
 1. **Docker Security:**
-   The container runs as root for simplicity. For production, consider additional security measures.
+   The container runs as a non-root user (UID/GID 1000 by default) for improved security. You can customize the user ID using build arguments to match your local user.
 
 2. **Volume Permissions:**
-   Ensure mounted directories have appropriate permissions and don't expose sensitive data.
+   Ensure mounted directories have appropriate permissions and don't expose sensitive data. With the non-root container, files will be created with the specified user ownership.
 
 3. **Network Security:**
    If using HTTP transport, consider using reverse proxy with SSL/TLS and authentication if the endpoint is available on
@@ -288,7 +319,7 @@ For Docker-specific issues:
 1. Check the [troubleshooting section](#troubleshooting) above
 2. Review container logs: `docker-compose logs basic-memory`
 3. Verify volume mounts: `docker inspect basic-memory-server`
-4. Test file permissions: `docker exec basic-memory-server ls -la /root`
+4. Test file permissions: `docker exec basic-memory-server ls -la /app`
 
 For general Basic Memory support, see the main [README](../README.md)
 and [documentation](https://memory.basicmachines.co/).

docs/character-handling.md

@@ -0,0 +1,241 @@
+# Character Handling and Conflict Resolution
+
+Basic Memory handles various character encoding scenarios and file naming conventions to provide consistent permalink generation and conflict resolution. This document explains how the system works and how to resolve common character-related issues.
+
+## Overview
+
+Basic Memory uses a sophisticated system to generate permalinks from file paths while maintaining consistency across different operating systems and character encodings. The system normalizes file paths and generates unique permalinks to prevent conflicts.
+
+## Character Normalization Rules
+
+### 1. Permalink Generation
+
+When Basic Memory processes a file path, it applies these normalization rules:
+
+```
+Original: "Finance/My Investment Strategy.md"
+Permalink: "finance/my-investment-strategy"
+```
+
+**Transformation process:**
+1. Remove file extension (`.md`)
+2. Convert to lowercase (case-insensitive)
+3. Replace spaces with hyphens
+4. Replace underscores with hyphens
+5. Handle international characters (transliteration for Latin, preservation for non-Latin)
+6. Convert camelCase to kebab-case
+
+### 2. International Character Support
+
+**Latin characters with diacritics** are transliterated:
+- `ø` → `o` (Søren → soren)
+- `ü` → `u` (Müller → muller)
+- `é` → `e` (Café → cafe)
+- `ñ` → `n` (Niño → nino)
+
+**Non-Latin characters** are preserved:
+- Chinese: `中文/测试文档.md` → `中文/测试文档`
+- Japanese: `日本語/文書.md` → `日本語/文書`
+
+## Common Conflict Scenarios
+
+### 1. Hyphen vs Space Conflicts
+
+**Problem:** Files with existing hyphens conflict with generated permalinks from spaces.
+
+**Example:**
+```
+File 1: "basic memory bug.md"     → permalink: "basic-memory-bug"
+File 2: "basic-memory-bug.md"    → permalink: "basic-memory-bug" (CONFLICT!)
+```
+
+**Resolution:** The system automatically resolves this by adding suffixes:
+```
+File 1: "basic memory bug.md"     → permalink: "basic-memory-bug"
+File 2: "basic-memory-bug.md"    → permalink: "basic-memory-bug-1"
+```
+
+**Best Practice:** Choose consistent naming conventions within your project.
+
+### 2. Case Sensitivity Conflicts
+
+**Problem:** Different case variations that normalize to the same permalink.
+
+**Example on macOS:**
+```
+Directory: Finance/investment.md
+Directory: finance/investment.md  (different on filesystem, same permalink)
+```
+
+**Resolution:** Basic Memory detects case conflicts and prevents them during sync operations with helpful error messages.
+
+**Best Practice:** Use consistent casing for directory and file names.
+
+### 3. Character Encoding Conflicts
+
+**Problem:** Different Unicode normalizations of the same logical character.
+
+**Example:**
+```
+File 1: "café.md" (é as single character)
+File 2: "café.md" (e + combining accent)
+```
+
+**Resolution:** Basic Memory normalizes Unicode characters using NFD normalization to detect these conflicts.
+
+### 4. Forward Slash Conflicts
+
+**Problem:** Forward slashes in frontmatter or file names interpreted as path separators.
+
+**Example:**
+```yaml
+---
+permalink: finance/investment/strategy
+---
+```
+
+**Resolution:** Basic Memory validates frontmatter permalinks and warns about path separator conflicts.
+
+## Error Messages and Troubleshooting
+
+### "UNIQUE constraint failed: entity.file_path, entity.project_id"
+
+**Cause:** Two entities trying to use the same file path within a project.
+
+**Common scenarios:**
+1. File move operation where destination is already occupied
+2. Case sensitivity differences on macOS
+3. Character encoding conflicts
+4. Concurrent file operations
+
+**Resolution steps:**
+1. Check for duplicate file names with different cases
+2. Look for files with similar names but different character encodings
+3. Rename conflicting files to have unique names
+4. Run sync again after resolving conflicts
+
+### "File path conflict detected during move"
+
+**Cause:** Enhanced conflict detection preventing potential database integrity violations.
+
+**What this means:** The system detected that moving a file would create a conflict before attempting the database operation.
+
+**Resolution:** Follow the specific guidance in the error message, which will indicate the type of conflict detected.
+
+## Best Practices
+
+### 1. File Naming Conventions
+
+**Recommended patterns:**
+- Use consistent casing (prefer lowercase)
+- Use hyphens instead of spaces for multi-word files
+- Avoid special characters that could conflict with path separators
+- Be consistent with directory structure casing
+
+**Examples:**
+```
+✅ Good:
+- finance/investment-strategy.md
+- projects/basic-memory-features.md
+- docs/api-reference.md
+
+❌ Problematic:
+- Finance/Investment Strategy.md  (mixed case, spaces)
+- finance/Investment Strategy.md  (inconsistent case)
+- docs/API/Reference.md          (mixed case directories)
+```
+
+### 2. Permalink Management
+
+**Custom permalinks in frontmatter:**
+```yaml
+---
+type: knowledge
+permalink: custom-permalink-name
+---
+```
+
+**Guidelines:**
+- Use lowercase permalinks
+- Use hyphens for word separation
+- Avoid path separators unless creating sub-paths
+- Ensure uniqueness within your project
+
+### 3. Directory Structure
+
+**Consistent casing:**
+```
+✅ Good:
+finance/
+  investment-strategies.md
+  portfolio-management.md
+
+❌ Problematic:  
+Finance/           (capital F)
+  investment-strategies.md
+finance/           (lowercase f) 
+  portfolio-management.md
+```
+
+## Migration and Cleanup
+
+### Identifying Conflicts
+
+Use Basic Memory's built-in conflict detection:
+
+```bash
+# Sync will report conflicts
+basic-memory sync
+
+# Check sync status for warnings
+basic-memory status
+```
+
+### Resolving Existing Conflicts
+
+1. **Identify conflicting files** from sync error messages
+2. **Choose consistent naming convention** for your project
+3. **Rename files** to follow the convention
+4. **Re-run sync** to verify resolution
+
+### Bulk Renaming Strategy
+
+For projects with many conflicts:
+
+1. **Backup your project** before making changes
+2. **Standardize on lowercase** file and directory names
+3. **Replace spaces with hyphens** in file names
+4. **Use consistent character encoding** (UTF-8)
+5. **Test sync after each batch** of changes
+
+## System Enhancements
+
+### Recent Improvements (v0.13+)
+
+1. **Enhanced conflict detection** before database operations
+2. **Improved error messages** with specific resolution guidance
+3. **Character normalization utilities** for consistent handling
+4. **File swap detection** for complex move scenarios
+5. **Proactive conflict warnings** during permalink resolution
+
+### Monitoring and Logging
+
+The system now provides detailed logging for conflict resolution:
+
+```
+DEBUG: Detected potential file path conflicts for 'Finance/Investment.md': ['finance/investment.md']
+WARNING: File path conflict detected during move: entity_id=123 trying to move from 'old.md' to 'new.md'
+```
+
+These logs help identify and resolve conflicts before they cause sync failures.
+
+## Support and Resources
+
+If you encounter character-related conflicts not covered in this guide:
+
+1. **Check the logs** for specific conflict details
+2. **Review error messages** for resolution guidance  
+3. **Report issues** with examples of the conflicting files
+4. **Consider the file naming best practices** outlined above
+
+The Basic Memory system is designed to handle most character conflicts automatically while providing clear guidance for manual resolution when needed.

docs/cloud-cli.md

@@ -0,0 +1,726 @@
+# Basic Memory Cloud CLI Guide
+
+The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using **project-scoped synchronization**. Each project can optionally sync with the cloud, giving you fine-grained control over what syncs and where.
+
+## Overview
+
+The cloud CLI enables you to:
+- **Toggle cloud mode** - All regular `bm` commands work with cloud when enabled
+- **Project-scoped sync** - Each project independently manages its sync configuration
+- **Explicit operations** - Sync only what you want, when you want
+- **Bidirectional sync** - Keep local and cloud in sync with rclone bisync
+- **Offline access** - Work locally, sync when ready
+
+## Prerequisites
+
+Before using Basic Memory Cloud, you need:
+
+- **Active Subscription**: An active Basic Memory Cloud subscription is required to access cloud features
+- **Subscribe**: Visit [https://basicmemory.com/subscribe](https://basicmemory.com/subscribe) to sign up
+
+If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error with a link to subscribe.
+
+## Architecture: Project-Scoped Sync
+
+### The Problem
+
+**Old approach (SPEC-8):** All projects lived in a single `~/basic-memory-cloud-sync/` directory. This caused:
+- ❌ Directory conflicts between mount and bisync
+- ❌ Auto-discovery creating phantom projects
+- ❌ Confusion about what syncs and when
+- ❌ All-or-nothing sync (couldn't sync just one project)
+
+**New approach (SPEC-20):** Each project independently configures sync.
+
+### How It Works
+
+**Projects can exist in three states:**
+
+1. **Cloud-only** - Project exists on cloud, no local copy
+2. **Cloud + Local (synced)** - Project has a local working directory that syncs
+3. **Local-only** - Project exists locally (when cloud mode is disabled)
+
+**Example:**
+
+```bash
+# You have 3 projects on cloud:
+# - research: wants local sync at ~/Documents/research
+# - work: wants local sync at ~/work-notes
+# - temp: cloud-only, no local sync needed
+
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work-notes
+bm project add temp  # No local sync
+
+# Now you can sync individually (after initial --resync):
+bm project bisync --name research
+bm project bisync --name work
+# temp stays cloud-only
+```
+
+**What happens under the covers:**
+- Config stores `cloud_projects` dict mapping project names to local paths
+- Each project gets its own bisync state in `~/.basic-memory/bisync-state/{project}/`
+- Rclone syncs using single remote: `basic-memory-cloud`
+- Projects can live anywhere on your filesystem, not forced into sync directory
+
+## Quick Start
+
+### 1. Enable Cloud Mode
+
+Authenticate and enable cloud mode:
+
+```bash
+bm cloud login
+```
+
+**What this does:**
+1. Opens browser to Basic Memory Cloud authentication page
+2. Stores authentication token in `~/.basic-memory/auth/token`
+3. **Enables cloud mode** - all CLI commands now work against cloud
+4. Validates your subscription status
+
+**Result:** All `bm project`, `bm tools` commands now work with cloud.
+
+### 2. Set Up Sync
+
+Install rclone and configure credentials:
+
+```bash
+bm cloud setup
+```
+
+**What this does:**
+1. Installs rclone automatically (if needed)
+2. Fetches your tenant information from cloud
+3. Generates scoped S3 credentials for sync
+4. Configures single rclone remote: `basic-memory-cloud`
+
+**Result:** You're ready to sync projects. No sync directories created yet - those come with project setup.
+
+### 3. Add Projects with Sync
+
+Create projects with optional local sync paths:
+
+```bash
+# Create cloud project without local sync
+bm project add research
+
+# Create cloud project WITH local sync
+bm project add research --local-path ~/Documents/research
+
+# Or configure sync for existing project
+bm project sync-setup research ~/Documents/research
+```
+
+**What happens under the covers:**
+
+When you add a project with `--local-path`:
+1. Project created on cloud at `/app/data/research`
+2. Local path stored in config: `cloud_projects.research.local_path = "~/Documents/research"`
+3. Local directory created if it doesn't exist
+4. Bisync state directory created at `~/.basic-memory/bisync-state/research/`
+
+**Result:** Project is ready to sync, but no files synced yet.
+
+### 4. Sync Your Project
+
+Establish the initial sync baseline. **Best practice:** Always preview with `--dry-run` first:
+
+```bash
+# Step 1: Preview the initial sync (recommended)
+bm project bisync --name research --resync --dry-run
+
+# Step 2: If all looks good, run the actual sync
+bm project bisync --name research --resync
+```
+
+**What happens under the covers:**
+1. Rclone reads from `~/Documents/research` (local)
+2. Connects to `basic-memory-cloud:bucket-name/app/data/research` (remote)
+3. Creates bisync state files in `~/.basic-memory/bisync-state/research/`
+4. Syncs files bidirectionally with settings:
+   - `conflict_resolve=newer` (most recent wins)
+   - `max_delete=25` (safety limit)
+   - Respects `.bmignore` patterns
+
+**Result:** Local and cloud are in sync. Baseline established.
+
+**Why `--resync`?** This is an rclone requirement for the first bisync run. It establishes the initial state that future syncs will compare against. After the first sync, never use `--resync` unless you need to force a new baseline.
+
+See: https://rclone.org/bisync/#resync
+```
+--resync
+This will effectively make both Path1 and Path2 filesystems contain a matching superset of all files. By default, Path2 files that do not exist in Path1 will be copied to Path1, and the process will then copy the Path1 tree to Path2.
+```
+
+### 5. Subsequent Syncs
+
+After the first sync, just run bisync without `--resync`:
+
+```bash
+bm project bisync --name research
+```
+
+**What happens:**
+1. Rclone compares local and cloud states
+2. Syncs changes in both directions
+3. Auto-resolves conflicts (newer file wins)
+4. Updates `last_sync` timestamp in config
+
+**Result:** Changes flow both ways - edit locally or in cloud, both stay in sync.
+
+### 6. Verify Setup
+
+Check status:
+
+```bash
+bm cloud status
+```
+
+You should see:
+- `Mode: Cloud (enabled)`
+- `Cloud instance is healthy`
+- Instructions for project sync commands
+
+## Working with Projects
+
+### Understanding Project Commands
+
+**Key concept:** When cloud mode is enabled, use regular `bm project` commands (not `bm cloud project`).
+
+```bash
+# In cloud mode:
+bm project list              # Lists cloud projects
+bm project add research      # Creates cloud project
+
+# In local mode:
+bm project list              # Lists local projects
+bm project add research ~/Documents/research  # Creates local project
+```
+
+### Creating Projects
+
+**Use case 1: Cloud-only project (no local sync)**
+
+```bash
+bm project add temp-notes
+```
+
+**What this does:**
+- Creates project on cloud at `/app/data/temp-notes`
+- No local directory created
+- No sync configuration
+
+**Result:** Project exists on cloud, accessible via MCP tools, but no local copy.
+
+**Use case 2: Cloud project with local sync**
+
+```bash
+bm project add research --local-path ~/Documents/research
+```
+
+**What this does:**
+- Creates project on cloud at `/app/data/research`
+- Creates local directory `~/Documents/research`
+- Stores sync config in `~/.basic-memory/config.json`
+- Prepares for bisync (but doesn't sync yet)
+
+**Result:** Project ready to sync. Run `bm project bisync --name research --resync` to establish baseline.
+
+**Use case 3: Add sync to existing cloud project**
+
+```bash
+# Project already exists on cloud
+bm project sync-setup research ~/Documents/research
+```
+
+**What this does:**
+- Updates existing project's sync configuration
+- Creates local directory
+- Prepares for bisync
+
+**Result:** Existing cloud project now has local sync path. Run bisync to pull files down.
+
+### Listing Projects
+
+View all projects:
+
+```bash
+bm project list
+```
+
+**What you see:**
+- All projects in cloud (when cloud mode enabled)
+- Default project marked
+- Project paths shown
+
+**Future:** Will show sync status (synced/not synced, last sync time).
+
+## File Synchronization
+
+### Understanding the Sync Commands
+
+**There are three sync-related commands:**
+
+1. `bm project sync` - One-way: local → cloud (make cloud match local)
+2. `bm project bisync` - Two-way: local ↔ cloud (recommended)
+3. `bm project check` - Verify files match (no changes)
+
+### One-Way Sync: Local → Cloud
+
+**Use case:** You made changes locally and want to push to cloud (overwrite cloud).
+
+```bash
+bm project sync --name research
+```
+
+**What happens:**
+1. Reads files from `~/Documents/research` (local)
+2. Uses rclone sync to make cloud identical to local
+3. Respects `.bmignore` patterns
+4. Shows progress bar
+
+**Result:** Cloud now matches local exactly. Any cloud-only changes are overwritten.
+
+**When to use:**
+- You know local is the source of truth
+- You want to force cloud to match local
+- You don't care about cloud changes
+
+### Two-Way Sync: Local ↔ Cloud (Recommended)
+
+**Use case:** You edit files both locally and in cloud UI, want both to stay in sync.
+
+```bash
+# First time - establish baseline
+bm project bisync --name research --resync
+
+# Subsequent syncs
+bm project bisync --name research
+```
+
+**What happens:**
+1. Compares local and cloud states using bisync metadata
+2. Syncs changes in both directions
+3. Auto-resolves conflicts (newer file wins)
+4. Detects excessive deletes and fails safely (max 25 files)
+
+**Conflict resolution example:**
+
+```bash
+# Edit locally
+echo "Local change" > ~/Documents/research/notes.md
+
+# Edit same file in cloud UI
+# Cloud now has: "Cloud change"
+
+# Run bisync
+bm project bisync --name research
+
+# Result: Newer file wins (based on modification time)
+# If cloud was more recent, cloud version kept
+# If local was more recent, local version kept
+```
+
+**When to use:**
+- Default workflow for most users
+- You edit in multiple places
+- You want automatic conflict resolution
+
+### Verify Sync Integrity
+
+**Use case:** Check if local and cloud match without making changes.
+
+```bash
+bm project check --name research
+```
+
+**What happens:**
+1. Compares file checksums between local and cloud
+2. Reports differences
+3. No files transferred
+
+**Result:** Shows which files differ. Run bisync to sync them.
+
+```bash
+# One-way check (faster)
+bm project check --name research --one-way
+```
+
+### Preview Changes (Dry Run)
+
+**Use case:** See what would change without actually syncing.
+
+```bash
+bm project bisync --name research --dry-run
+```
+
+**What happens:**
+1. Runs bisync logic
+2. Shows what would be transferred/deleted
+3. No actual changes made
+
+**Result:** Safe preview of sync operations.
+
+### Advanced: List Remote Files
+
+**Use case:** See what files exist on cloud without syncing.
+
+```bash
+# List all files in project
+bm project ls --name research
+
+# List files in subdirectory
+bm project ls --name research --path subfolder
+```
+
+**What happens:**
+1. Connects to cloud via rclone
+2. Lists files in remote project path
+3. No files transferred
+
+**Result:** See cloud file listing.
+
+## Multiple Projects
+
+### Syncing Multiple Projects
+
+**Use case:** You have several projects with local sync, want to sync all at once.
+
+```bash
+# Setup multiple projects
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work-notes
+bm project add personal --local-path ~/personal
+
+# Establish baselines
+bm project bisync --name research --resync
+bm project bisync --name work --resync
+bm project bisync --name personal --resync
+
+# Daily workflow: sync everything
+bm project bisync --name research
+bm project bisync --name work
+bm project bisync --name personal
+```
+
+**Future:** `--all` flag will sync all configured projects:
+
+```bash
+bm project bisync --all  # Coming soon
+```
+
+### Mixed Usage
+
+**Use case:** Some projects sync, some stay cloud-only.
+
+```bash
+# Projects with sync
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work
+
+# Cloud-only projects
+bm project add archive
+bm project add temp-notes
+
+# Sync only the configured ones
+bm project bisync --name research
+bm project bisync --name work
+
+# Archive and temp-notes stay cloud-only
+```
+
+**Result:** Fine-grained control over what syncs.
+
+## Disable Cloud Mode
+
+Return to local mode:
+
+```bash
+bm cloud logout
+```
+
+**What this does:**
+1. Disables cloud mode in config
+2. All commands now work locally
+3. Auth token remains (can re-enable with login)
+
+**Result:** All `bm` commands work with local projects again.
+
+## Filter Configuration
+
+### Understanding .bmignore
+
+**The problem:** You don't want to sync everything (e.g., `.git`, `node_modules`, database files).
+
+**The solution:** `.bmignore` file with gitignore-style patterns.
+
+**Location:** `~/.basic-memory/.bmignore`
+
+**Default patterns:**
+
+```gitignore
+# Version control
+.git/**
+
+# Python
+__pycache__/**
+*.pyc
+.venv/**
+venv/**
+
+# Node.js
+node_modules/**
+
+# Basic Memory internals
+memory.db/**
+memory.db-shm/**
+memory.db-wal/**
+config.json/**
+watch-status.json/**
+.bmignore.rclone/**
+
+# OS files
+.DS_Store/**
+Thumbs.db/**
+
+# Environment files
+.env/**
+.env.local/**
+```
+
+**How it works:**
+1. On first sync, `.bmignore` created with defaults
+2. Patterns converted to rclone filter format (`.bmignore.rclone`)
+3. Rclone uses filters during sync
+4. Same patterns used by all projects
+
+**Customizing:**
+
+```bash
+# Edit patterns
+code ~/.basic-memory/.bmignore
+
+# Add custom patterns
+echo "*.tmp/**" >> ~/.basic-memory/.bmignore
+
+# Next sync uses updated patterns
+bm project bisync --name research
+```
+
+## Troubleshooting
+
+### Authentication Issues
+
+**Problem:** "Authentication failed" or "Invalid token"
+
+**Solution:** Re-authenticate:
+
+```bash
+bm cloud logout
+bm cloud login
+```
+
+### Subscription Issues
+
+**Problem:** "Subscription Required" error
+
+**Solution:**
+1. Visit subscribe URL shown in error
+2. Sign up for subscription
+3. Run `bm cloud login` again
+
+**Note:** Access is immediate when subscription becomes active.
+
+### Bisync Initialization
+
+**Problem:** "First bisync requires --resync"
+
+**Explanation:** Bisync needs a baseline state before it can sync changes.
+
+**Solution:**
+
+```bash
+bm project bisync --name research --resync
+```
+
+**What this does:**
+- Establishes initial sync state
+- Creates baseline in `~/.basic-memory/bisync-state/research/`
+- Syncs all files bidirectionally
+
+**Result:** Future syncs work without `--resync`.
+
+### Empty Directory Issues
+
+**Problem:** "Empty prior Path1 listing. Cannot sync to an empty directory"
+
+**Explanation:** Rclone bisync doesn't work well with completely empty directories. It needs at least one file to establish a baseline.
+
+**Solution:** Add at least one file before running `--resync`:
+
+```bash
+# Create a placeholder file
+echo "# Research Notes" > ~/Documents/research/README.md
+
+# Now run bisync
+bm project bisync --name research --resync
+```
+
+**Why this happens:** Bisync creates listing files that track the state of each side. When both directories are completely empty, these listing files are considered invalid by rclone.
+
+**Best practice:** Always have at least one file (like a README.md) in your project directory before setting up sync.
+
+### Bisync State Corruption
+
+**Problem:** Bisync fails with errors about corrupted state or listing files
+
+**Explanation:** Sometimes bisync state can become inconsistent (e.g., after mixing dry-run and actual runs, or after manual file operations).
+
+**Solution:** Clear bisync state and re-establish baseline:
+
+```bash
+# Clear bisync state
+bm project bisync-reset research
+
+# Re-establish baseline
+bm project bisync --name research --resync
+```
+
+**What this does:**
+- Removes all bisync metadata from `~/.basic-memory/bisync-state/research/`
+- Forces fresh baseline on next `--resync`
+- Safe operation (doesn't touch your files)
+
+**Note:** This command also runs automatically when you remove a project to clean up state directories.
+
+### Too Many Deletes
+
+**Problem:** "Error: max delete limit (25) exceeded"
+
+**Explanation:** Bisync detected you're about to delete more than 25 files. This is a safety check to prevent accidents.
+
+**Solution 1:** Review what you're deleting, then force resync:
+
+```bash
+# Check what would be deleted
+bm project bisync --name research --dry-run
+
+# If correct, establish new baseline
+bm project bisync --name research --resync
+```
+
+**Solution 2:** Use one-way sync if you know local is correct:
+
+```bash
+bm project sync --name research
+```
+
+### Project Not Configured for Sync
+
+**Problem:** "Project research has no local_sync_path configured"
+
+**Explanation:** Project exists on cloud but has no local sync path.
+
+**Solution:**
+
+```bash
+bm project sync-setup research ~/Documents/research
+bm project bisync --name research --resync
+```
+
+### Connection Issues
+
+**Problem:** "Cannot connect to cloud instance"
+
+**Solution:** Check status:
+
+```bash
+bm cloud status
+```
+
+If instance is down, wait a few minutes and retry.
+
+## Security
+
+- **Authentication**: OAuth 2.1 with PKCE flow
+- **Tokens**: Stored securely in `~/.basic-memory/basic-memory-cloud.json`
+- **Transport**: All data encrypted in transit (HTTPS)
+- **Credentials**: Scoped S3 credentials (read-write to your tenant only)
+- **Isolation**: Your data isolated from other tenants
+- **Ignore patterns**: Sensitive files automatically excluded via `.bmignore`
+
+## Command Reference
+
+### Cloud Mode Management
+
+```bash
+bm cloud login              # Authenticate and enable cloud mode
+bm cloud logout             # Disable cloud mode
+bm cloud status             # Check cloud mode and instance health
+```
+
+### Setup
+
+```bash
+bm cloud setup              # Install rclone and configure credentials
+```
+
+### Project Management
+
+When cloud mode is enabled:
+
+```bash
+bm project list                           # List cloud projects
+bm project add <name>                     # Create cloud project (no sync)
+bm project add <name> --local-path <path> # Create with local sync
+bm project sync-setup <name> <path>       # Add sync to existing project
+bm project rm <name>                      # Delete project
+```
+
+### File Synchronization
+
+```bash
+# One-way sync (local → cloud)
+bm project sync --name <project>
+bm project sync --name <project> --dry-run
+bm project sync --name <project> --verbose
+
+# Two-way sync (local ↔ cloud) - Recommended
+bm project bisync --name <project>          # After first --resync
+bm project bisync --name <project> --resync # First time / force baseline
+bm project bisync --name <project> --dry-run
+bm project bisync --name <project> --verbose
+
+# Integrity check
+bm project check --name <project>
+bm project check --name <project> --one-way
+
+# List remote files
+bm project ls --name <project>
+bm project ls --name <project> --path <subpath>
+```
+
+## Summary
+
+**Basic Memory Cloud uses project-scoped sync:**
+
+1. **Enable cloud mode** - `bm cloud login`
+2. **Install rclone** - `bm cloud setup`
+3. **Add projects with sync** - `bm project add research --local-path ~/Documents/research`
+4. **Preview first sync** - `bm project bisync --name research --resync --dry-run`
+5. **Establish baseline** - `bm project bisync --name research --resync`
+6. **Daily workflow** - `bm project bisync --name research`
+
+**Key benefits:**
+- ✅ Each project independently syncs (or doesn't)
+- ✅ Projects can live anywhere on disk
+- ✅ Explicit sync operations (no magic)
+- ✅ Safe by design (max delete limits, conflict resolution)
+- ✅ Full offline access (work locally, sync when ready)
+
+**Future enhancements:**
+- `--all` flag to sync all configured projects
+- Project list showing sync status
+- Watch mode for automatic sync

docs/testing-coverage.md

@@ -0,0 +1,28 @@
+## Coverage policy (practical 100%)
+
+Basic Memory’s test suite intentionally mixes:
+- unit tests (fast, deterministic)
+- integration tests (real filesystem + real DB via `test-int/`)
+
+To keep the default CI signal **stable and meaningful**, the default `pytest` coverage report targets **core library logic** and **excludes** a small set of modules that are either:
+- highly environment-dependent (OS/DB tuning)
+- inherently interactive (CLI)
+- background-task orchestration (watchers/sync runners)
+
+### What's excluded (and why)
+
+Coverage excludes are configured in `pyproject.toml` under `[tool.coverage.report].omit`.
+
+Current exclusions include:
+- `src/basic_memory/cli/**`: interactive wrappers; behavior is validated via higher-level tests and smoke tests.
+- `src/basic_memory/db.py`: platform/backend tuning paths (SQLite/Postgres/Windows), covered by integration tests and targeted runs.
+- `src/basic_memory/services/initialization.py`: startup orchestration/background tasks; covered indirectly by app/MCP entrypoints.
+- `src/basic_memory/sync/sync_service.py`: heavy filesystem↔DB integration; validated in integration suite (not enforced in unit coverage).
+
+### Recommended additional runs
+
+If you want extra confidence locally/CI:
+- **Postgres backend**: run tests with `BASIC_MEMORY_TEST_POSTGRES=1`.
+- **Strict backend-complete coverage**: run coverage on SQLite + Postgres and combine the results (recommended).
+
+

justfile

@@ -2,25 +2,136 @@
 
 # Install dependencies
 install:
-    pip install -e ".[dev]"
+    uv pip install -e ".[dev]"
+    uv sync
+    @echo ""
+    @echo "💡 Remember to activate the virtual environment by running: source .venv/bin/activate"
 
-# Run unit tests in parallel
-test-unit:
-    uv run pytest -p pytest_mock -v -n auto
+# ==============================================================================
+# DATABASE BACKEND TESTING
+# ==============================================================================
+# Basic Memory supports dual database backends (SQLite and Postgres).
+# By default, tests run against SQLite (fast, no dependencies).
+# Set BASIC_MEMORY_TEST_POSTGRES=1 to run against Postgres (uses testcontainers).
+#
+# Quick Start:
+#   just test              # Run all tests against SQLite (default)
+#   just test-sqlite       # Run all tests against SQLite
+#   just test-postgres     # Run all tests against Postgres (testcontainers)
+#   just test-unit-sqlite  # Run unit tests against SQLite
+#   just test-unit-postgres # Run unit tests against Postgres
+#   just test-int-sqlite   # Run integration tests against SQLite
+#   just test-int-postgres # Run integration tests against Postgres
+#
+# CI runs both in parallel for faster feedback.
+# ==============================================================================
 
-# Run integration tests in parallel
-test-int:
-    uv run pytest -p pytest_mock -v --no-cov -n auto test-int
+# Run all tests against SQLite and Postgres
+test: test-sqlite test-postgres
 
-# Run all tests
-test: test-unit test-int
+# Run all tests against SQLite
+test-sqlite: test-unit-sqlite test-int-sqlite
+
+# Run all tests against Postgres (uses testcontainers)
+test-postgres: test-unit-postgres test-int-postgres
+
+# Run unit tests against SQLite
+test-unit-sqlite:
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov tests
+
+# Run unit tests against Postgres
+test-unit-postgres:
+    BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov tests
+
+# Run integration tests against SQLite
+test-int-sqlite:
+    uv run pytest -p pytest_mock -v --no-cov test-int
+
+# Run integration tests against Postgres
+# Note: Uses timeout due to FastMCP Client + asyncpg cleanup hang (tests pass, process hangs on exit)
+# See: https://github.com/jlowin/fastmcp/issues/1311
+test-int-postgres:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    # Use gtimeout (macOS/Homebrew) or timeout (Linux)
+    TIMEOUT_CMD=$(command -v gtimeout || command -v timeout || echo "")
+    if [[ -n "$TIMEOUT_CMD" ]]; then
+        $TIMEOUT_CMD --signal=KILL 600 bash -c 'BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov test-int' || test $? -eq 137
+    else
+        echo "⚠️  No timeout command found, running without timeout..."
+        BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov test-int
+    fi
+
+# 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+asyncpg://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:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    
+    uv run coverage erase
+    
+    echo "🔎 Coverage (SQLite)..."
+    BASIC_MEMORY_ENV=test uv run coverage run --source=basic_memory -m pytest -p pytest_mock -v --no-cov tests test-int
+    
+    echo "🔎 Coverage (Postgres via testcontainers)..."
+    # Note: Uses timeout due to FastMCP Client + asyncpg cleanup hang (tests pass, process hangs on exit)
+    # See: https://github.com/jlowin/fastmcp/issues/1311
+    TIMEOUT_CMD=$(command -v gtimeout || command -v timeout || echo "")
+    if [[ -n "$TIMEOUT_CMD" ]]; then
+        $TIMEOUT_CMD --signal=KILL 600 bash -c 'BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run coverage run --source=basic_memory -m pytest -p pytest_mock -v --no-cov -m postgres tests test-int' || test $? -eq 137
+    else
+        echo "⚠️  No timeout command found, running without timeout..."
+        BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run coverage run --source=basic_memory -m pytest -p pytest_mock -v --no-cov -m postgres tests test-int
+    fi
+    
+    echo "🧩 Combining coverage data..."
+    uv run coverage combine
+    uv run coverage report -m
+    uv run coverage html
+    echo "Coverage report generated in htmlcov/index.html"
+
+# Lint and fix code (calls fix)
+lint: fix
 
 # Lint and fix code
-lint:
-    ruff check . --fix
+fix:
+    uv run ruff check --fix --unsafe-fixes src tests test-int
 
 # Type check code
-type-check:
+typecheck:
     uv run pyright
 
 # Clean build artifacts and cache files
@@ -38,21 +149,13 @@ format:
 run-inspector:
     npx @modelcontextprotocol/inspector
 
-# Build macOS installer
-installer-mac:
-    cd installer && chmod +x make_icons.sh && ./make_icons.sh
-    cd installer && uv run python setup.py bdist_mac
-
-# Build Windows installer
-installer-win:
-    cd installer && uv run python setup.py bdist_win32
 
 # Update all dependencies to latest versions
 update-deps:
     uv sync --upgrade
 
 # Run all code quality checks and tests
-check: lint format type-check test
+check: lint format typecheck test
 
 # Generate Alembic migration with descriptive message
 migration message:
@@ -93,16 +196,22 @@ release version:
     fi
     
     # Run quality checks
-    echo "🔍 Running quality checks..."
-    just check
+    echo "🔍 Running lint  checks..."
+    just lint
+    just typecheck
     
     # Update version in __init__.py
     echo "📝 Updating version in __init__.py..."
     sed -i.bak "s/__version__ = \".*\"/__version__ = \"$VERSION_NUM\"/" src/basic_memory/__init__.py
     rm -f src/basic_memory/__init__.py.bak
-    
+
+    # Update version in server.json (MCP registry metadata)
+    echo "📝 Updating version in server.json..."
+    sed -i.bak "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION_NUM\"/g" server.json
+    rm -f server.json.bak
+
     # Commit version update
-    git add src/basic_memory/__init__.py
+    git add src/basic_memory/__init__.py server.json
     git commit -m "chore: update version to $VERSION_NUM for {{version}} release"
     
     # Create and push tag
@@ -116,6 +225,12 @@ release version:
     echo "✅ Release {{version}} created successfully!"
     echo "📦 GitHub Actions will build and publish to PyPI"
     echo "🔗 Monitor at: https://github.com/basicmachines-co/basic-memory/actions"
+    echo ""
+    echo "📝 REMINDER: Post-release tasks:"
+    echo "   1. docs.basicmemory.com - Add release notes to src/pages/latest-releases.mdx"
+    echo "   2. basicmachines.co - Update version in src/components/sections/hero.tsx"
+    echo "   3. MCP Registry - Run: mcp-publisher publish"
+    echo "   See: .claude/commands/release/release.md for detailed instructions"
 
 # Create a beta release (e.g., just beta v0.13.2b1)
 beta version:
@@ -152,16 +267,22 @@ beta version:
     fi
     
     # Run quality checks
-    echo "🔍 Running quality checks..."
-    just check
+    echo "🔍 Running lint  checks..."
+    just lint
+    just typecheck
     
     # Update version in __init__.py
     echo "📝 Updating version in __init__.py..."
     sed -i.bak "s/__version__ = \".*\"/__version__ = \"$VERSION_NUM\"/" src/basic_memory/__init__.py
     rm -f src/basic_memory/__init__.py.bak
-    
+
+    # Update version in server.json (MCP registry metadata)
+    echo "📝 Updating version in server.json..."
+    sed -i.bak "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION_NUM\"/g" server.json
+    rm -f server.json.bak
+
     # Commit version update
-    git add src/basic_memory/__init__.py
+    git add src/basic_memory/__init__.py server.json
     git commit -m "chore: update version to $VERSION_NUM for {{version}} beta release"
     
     # Create and push tag
@@ -176,7 +297,12 @@ beta version:
     echo "📦 GitHub Actions will build and publish to PyPI as pre-release"
     echo "🔗 Monitor at: https://github.com/basicmachines-co/basic-memory/actions"
     echo "📥 Install with: uv tool install basic-memory --pre"
+    echo ""
+    echo "📝 REMINDER: For stable releases, update documentation sites:"
+    echo "   1. docs.basicmemory.com - Add release notes to src/pages/latest-releases.mdx"
+    echo "   2. basicmachines.co - Update version in src/components/sections/hero.tsx"
+    echo "   See: .claude/commands/release/release.md for detailed instructions"
 
 # List all available recipes
 default:
-    @just --list
+    @just --list

memory.json

@@ -1,378 +0,0 @@
-{"type":"entity","name":"Paul","entityType":"person","observations":["Software developer combining DIY ethics, Free Software principles, and theoretical computer science","Created the Basic Machines project","Values authentic exchange of ideas","Approaches AI interaction with emphasis on genuine technical discussion","Comfortable with uncertainty and open dialogue","Balances practical implementation with broader implications"]}
-{"type":"entity","name":"Basic_Machines","entityType":"project","observations":["Local-first knowledge management system","Combines filesystem durability with graph-based knowledge representation","Focuses on enhancing human agency and understanding","Synthesizes DIY ethics, Free Software philosophy, and theoretical computer science","Current focus includes basic-memory system"]}
-{"type":"entity","name":"basic-memory","entityType":"software_system","observations":["A core component of Basic Machines","Local-first knowledge management system","Combines filesystem persistence with graph-based knowledge representation","Being implemented collaboratively by Paul and Claude"]}
-{"type":"entity","name":"basic-memory_implementation_patterns","entityType":"technical_patterns","observations":["Filesystem is source of truth - all changes write to files first","Clean separation of concerns between models (SQLAlchemy), schemas (Pydantic), and services","Repository pattern for database access","Service layer handling business logic and coordination","Atomic file operations using temporary files for safety","Clear error handling hierarchy with specific error types","Comprehensive test coverage with pytest and fixtures","Async/await used throughout the codebase","Validation using Pydantic models with custom validators"]}
-{"type":"entity","name":"fileio_module","entityType":"code_module","observations":["Extracted from EntityService to handle all file operations","Provides read_entity_file, write_entity_file, and delete_entity_file functions","Handles markdown parsing and formatting","Implements atomic file operations","Provides consistent error handling","Enables reuse across services"]}
-{"type":"entity","name":"entity_service","entityType":"code_module","observations":["Manages entities in both filesystem and database","Uses fileio module for file operations","Maintains database index of entities","Handles entity creation, retrieval, and deletion","Follows 'filesystem is source of truth' principle","Coordinates with observation service for full entity management"]}
-{"type":"entity","name":"observation_service","entityType":"code_module","observations":["Manages observations within entity files","Provides database indexing for efficient observation queries","Works with complete Entity objects rather than IDs","Handles observation addition and search","Maintains consistency between files and database","Under development for update/remove operations"]}
-{"type":"entity","name":"observation_management","entityType":"design_challenge","observations":["Key challenge: maintaining observation state across files and database","Exploring bulk update approach - treating all observations as a unit","Considering tracked observations with markdown comments for IDs","Investigating diff-based approach for observation-level changes","Evaluating position-based management without explicit IDs","Trade-offs between implementation complexity and markdown readability"]}
-{"type":"entity","name":"testing_infrastructure","entityType":"technical_patterns","observations":["Uses pytest with async support via pytest-asyncio","In-memory SQLite database for test isolation","Temporary directories for file operation testing","Comprehensive fixture system for test setup","Tests organized by component (entity, observation, etc)","Covers happy path, error cases, and edge cases","Uses monkeypatch for mocking dependencies","Clear separation between arrange, act, assert sections","Uses in-memory SQLite database for test isolation","Comprehensive fixture system for test data setup","Proper async test handling with pytest-asyncio"]}
-{"type":"entity","name":"test_categories","entityType":"test_suite","observations":["Happy path tests verify core functionality","Error path tests ensure proper error handling","Edge cases test special characters and long content","File operation tests verify atomic writes and rollbacks","Database sync tests verify index consistency","Recovery tests for rebuild operations","Punted on concurrent operation tests due to session management complexity"]}
-{"type":"entity","name":"completed_work","entityType":"project_milestone","observations":["Extracted file operations to fileio.py module","Updated EntityService to use fileio functions","Implemented initial ObservationService","Created comprehensive test suite","Established clear project patterns and principles","Set up basic database schema with SQLAlchemy","Created Pydantic models for validation"]}
-{"type":"entity","name":"future_work","entityType":"project_tasks","observations":["Implement observation updates/removals","Design proper session management for concurrent operations","Update EntityService tests for new fileio module","Add more sophisticated search functionality","Handle markdown formatting edge cases","Consider versioning for file changes","Implement proper backup strategy"]}
-{"type":"entity","name":"design_decisions","entityType":"technical_decisions","observations":["Filesystem as source of truth over database","Markdown format for human readability and editing","Atomic file operations for safety","SQLite + SQLAlchemy for proven reliability","Pydantic for validation and ID generation","Async/await for better scalability","Clear separation between files and database roles","Explicit error hierarchies for better handling"]}
-{"type":"entity","name":"concurrency_considerations","entityType":"technical_challenge","observations":["SQLAlchemy session management in async context","File operation atomicity","Transaction isolation levels","Potential for conflicting updates","Need for proper session lifecycle","Possibility of file system race conditions","Database lock management"]}
-{"type":"entity","name":"observation_update_approaches","entityType":"design_alternatives","observations":["Each approach trades off between simplicity, efficiency, and robustness","Four main approaches considered: bulk update, tracked IDs, diff-based, and position-based","Discussion revealed importance of human readability in file format","Consideration of manual editing workflows key to design","File system as source of truth principle guides tradeoffs"]}
-{"type":"entity","name":"bulk_update_approach","entityType":"design_option","observations":["Update all observations at once in a single operation","Simpler file operations - just rewrite the whole list","No need for observation matching or IDs","Very consistent with source of truth principle","Less efficient for small changes","May have concurrency implications","Simplest implementation option"]}
-{"type":"entity","name":"tracked_observations_approach","entityType":"design_option","observations":["Use markdown comments to store observation IDs","Enables precise updates and deletes","IDs stored as HTML comments in markdown","More complex markdown parsing required","IDs visible in raw markdown files","Balances tracking with readability"]}
-{"type":"entity","name":"diff_based_approach","entityType":"design_option","observations":["Implement observation-aware diffing","Track changes at observation level","More efficient for updates","Preserves manual edits and changes","More complex implementation needed","Must handle merge conflicts","Most sophisticated option considered"]}
-{"type":"entity","name":"position_based_approach","entityType":"design_option","observations":["Track observations by position/order","No explicit IDs needed","Cleanest markdown format","Order changes could break references","Difficult to handle concurrent edits","Most fragile option considered"]}
-{"type":"entity","name":"tasks_and_progress","entityType":"project_tracking","observations":["Current focus on observation management implementation","Completed core file operations extraction","Completed EntityService updates","Completed initial ObservationService","Basic test coverage in place","Future work includes concurrent operations","Future work includes search improvements","Need to handle markdown edge cases"]}
-{"type":"entity","name":"error_handling_patterns","entityType":"technical_patterns","observations":["Custom exception hierarchy with ServiceError base","Specific error types (FileOperationError, DatabaseSyncError, etc)","Clear separation between file and database errors","Error propagation patterns established","Focus on actionable error messages","Error handling at appropriate levels"]}
-{"type":"entity","name":"data_models","entityType":"technical_implementation","observations":["SQLAlchemy models for database structure","Pydantic schemas for API/service layer","Entity model with UUID-based IDs","Observation model with entity relationships","UTCDateTime custom type for timestamps","Automatic ID generation in Pydantic models","Strict validation rules"]}
-{"type":"entity","name":"markdown_format","entityType":"file_format","observations":["Simple, human-readable format","Entity name as H1 header","Metadata in key-value format","Observations as bullet points","Atomic file operations for updates","Designed for manual editing","No hidden metadata in main content"]}
-{"type":"entity","name":"test_driven_development","entityType":"development_pattern","observations":["Tests revealed need for atomic file operations","Error cases drove error hierarchy design","Edge cases informed validation rules","Test fixtures shaped service interfaces","File operations extracted due to test patterns","Concurrent test issues revealed session management needs"]}
-{"type":"entity","name":"architecture_evolution","entityType":"design_process","observations":["Started with simple EntityService implementation","Circular dependency between Entity and Observation services revealed design flaw","Extracted file operations to separate module","Moved to passing Entity objects rather than IDs","Improved separation of concerns through iterations","File operations became reusable across services","Database became true 'index' rather than source of truth"]}
-{"type":"entity","name":"validation_patterns","entityType":"technical_patterns","observations":["Pydantic models provide schema validation","Automatic ID generation if not provided","Database constraints via SQLAlchemy","Runtime checks in services","Markdown format validation","Error handling for invalid states"]}
-{"type":"entity","name":"markdown_examples","entityType":"documentation","observations":["Example of basic entity:\n# Entity Name\ntype: entity_type\n\n## Observations\n- First observation\n- Second observation","Example with special characters:\n# Test & Entity!\ntype: test\n\n## Observations\n- Test & observation with @#$% special chars!","Format ensures human readability:\n# Basic Machines\ntype: project\n\n## Observations\n- Local-first knowledge management system\n- Combines filesystem durability with graph-based knowledge representation","Future consideration for observation IDs:\n# Entity Name\ntype: entity_type\n\n## Observations\n- <!-- obs-id: abc123 -->\n  This is an observation with ID"]}
-{"type":"entity","name":"markdown_parsing_rules","entityType":"technical_implementation","observations":["H1 header contains entity name","Metadata uses key: value format","Observations section marked by H2 header","Each observation is a markdown list item","Blank lines separate sections","Special characters allowed in content","No restrictions on observation content"]}
-{"type":"entity","name":"schema_definitions","entityType":"technical_documentation","observations":["SQLAlchemy Entity model:\nclass Entity(Base):\n    id: str (primary key)\n    name: str (unique)\n    entity_type: str\n    created_at: datetime\n    updated_at: datetime","SQLAlchemy Observation model:\nclass Observation(Base):\n    id: str (primary key)\n    entity_id: str (foreign key)\n    content: str\n    created_at: datetime\n    context: Optional[str]","Pydantic Entity schema:\nclass Entity(BaseModel):\n    id: str\n    name: str\n    entity_type: str\n    observations: List[Observation]"]}
-{"type":"entity","name":"test_evolution","entityType":"development_history","observations":["Started with basic Entity CRUD tests","Added filesystem verification to all tests","Developed concurrent operation tests (later removed)","Edge case tests drove better error handling","Test fixtures evolved to support both file and DB testing","Mocking patterns for file/DB operations","Special cases for long content and special characters"]}
-{"type":"entity","name":"implementation_challenges","entityType":"technical_issues","observations":["Initial circular dependency between services","SQLAlchemy session management in async context","Atomic file operations with proper error handling","Maintaining DB sync with filesystem changes","Handling long content in observations","Managing test isolation with file operations","Deciding on markdown format tradeoffs","Concurrent operation complexity"]}
-{"type":"entity","name":"Basic_Factory","entityType":"Project","observations":["Collaborative project between Paul and Claude","Explores AI-human collaboration in software development","Uses MCP tools for file and memory management","Built with git integration capabilities","Focuses on maintaining project context across sessions","About 90% complete with MCP tools","Still needs improvements in collaboration via files/git/github","Will be used to document and share collaborative development process"]}
-{"type":"entity","name":"Basic_Factory_Components","entityType":"Technical","observations":["Server-side rendering with JinjaX","HTMX for dynamic updates","Alpine.js for client-side state","Tailwind CSS for styling","Component translation from React/shadcn/ui","Focus on simplicity and understandability","Demonstrates meta-compiler principles in component translation"]}
-{"type":"entity","name":"Component_Translation_Process","entityType":"Methodology","observations":["Treats component porting as meta-compilation","Maps between React/TypeScript and JinjaX/Alpine.js domains","Uses formal grammar transformation approaches","Maintains functionality while simplifying implementation","Focuses on server-side rendering patterns","Preserves accessibility and performance","Uses short, focused git branches for each component"]}
-{"type":"entity","name":"Basic_Machines_Philosophy","entityType":"Philosophy","observations":["Combines DIY punk ethics with software development","Emphasizes user empowerment and understanding","Values simplicity and composability","Treats complex systems as combinations of simple parts","Focuses on authentic creation and sharing","Draws inspiration from punk rock, Free Software, and theoretical CS","Emphasizes the cycle of creation, complexity, and renewal"]}
-{"type":"entity","name":"Basic_Machines_Manifesto","entityType":"Document","observations":["Created through collaboration between Paul and Claude","Explores connection between DIY punk ethics and software development","Emphasizes composition over inheritance in both philosophy and practice","Views software development through lens of basic machines that combine for complex computation","Advocates for user empowerment and technological independence","Structured in sections covering Origins, Philosophy, Technical Implementation, and AI Collaboration","Draws connections between punk rock, free software, and theoretical computer science","Emphasizes importance of sharing knowledge and building community","Released in December 2024"]}
-{"type":"entity","name":"AI_Human_Collaboration_Model","entityType":"Methodology","observations":["Focuses on deep collaboration rather than simple task completion","Maintains rich context across sessions via knowledge graph","Uses short, focused git branches for each collaborative session","Values intellectual partnership over simple code generation","Emphasizes both practical implementation and theoretical exploration","Creates space for authentic exchange while maintaining AI/human clarity","Uses formal methods when appropriate (like grammar transformation)","Documents decisions and processes for future reference","Developed through Basic Machines project experience"]}
-{"type":"entity","name":"Basic_Machines_Roadmap","entityType":"Project_Plan","observations":["Phase 1 (30 days): Build basic-machines.co website","Phase 2 (60-90 days): Develop premium component bundles","Phase 3 (90-120 days): Launch Basic Foundation commercial offering","Focus on building brand and marketing presence","Prioritize components needed for own site development","Document and share collaboration process","Build sustainable business model aligned with values"]}
-{"type":"entity","name":"Basic_Machines_Website","entityType":"Project","observations":["To be built at basic-machines.co","Will showcase products and vision","Needs components for navigation, hero sections, features","Will demonstrate component usage in production","Will include blog for sharing progress","Focus on clear value proposition","Platform for sharing Basic Machines philosophy"]}
-{"type":"entity","name":"Basic_Memory_Markdown_Example","entityType":"Example","observations":["Shows complete markdown structure for basic-memory entity","Uses frontmatter for metadata (id, type, created, context)","Has main description section after title","Includes Observations as bullet points","Shows Relations with [id] relation_type | context format","Lists References at bottom","Created during initial design discussion","Serves as canonical example of file format"]}
-{"type":"entity","name":"Basic_Memory_Database_Schema","entityType":"Technical","observations":["Uses SQLite for local storage","Entities table with id, name, type, created_at, context, description, references","Observations table linking to entities with content and context","Relations table tracking directional relationships between entities","References column needs quotes as SQL reserved word","Designed for easy rebuilding from markdown files","Foreign key constraints maintain data integrity","Unique constraint on relations prevents duplicates","Created_at timestamps track history","Context fields enable tracking information sources"]}
-{"type":"entity","name":"Basic_Memory_Project_Structure","entityType":"Technical","observations":["Uses dbmate for database migrations","Projects directory stores SQLite databases and markdown files","Makefile provides common development commands","Environment vars configure database connection","db/migrations directory for SQL schema changes","Gitignore excludes database files and env config","Uses Python 3.12 with modern tooling","Tests directory for pytest files","Follows Basic Machines project conventions"]}
-{"type":"entity","name":"Basic_Memory_Project_Isolation_Decision","entityType":"Decision","observations":["Decided to defer multi-project support to post-MVP","Will use separate SQLite databases per project","Initially using projects directory in code repository","Plan to make location configurable later","No changes needed to core domain model","Keeps initial implementation simple","FTS/search capabilities also deferred for simplicity"]}
-{"type":"entity","name":"Basic_Memory_Implementation_Plan","entityType":"Plan","observations":["Start with SQLAlchemy models matching schema","Then build CLI for basic operations","Then implement markdown parser","Use TDD approach throughout","Begin with core domain model","CLI will support CRUD operations","Parser must handle frontmatter and sections","Following modular development approach","Planning to use typer for CLI","Will use modern Python tools and practices"]}
-{"type":"entity","name":"Basic_Memory_Implementation_Status","entityType":"Status","observations":["Core modules implemented: models, services, repository, fileio","Modular architecture with clear separation of concerns","File operations extracted to separate fileio module","Initial ObservationService implementation complete","Basic test coverage in place","Exploring observation management strategies","Using SQLAlchemy for database interaction","Markdown file operations working","Entity management functional","Repository layer implementation complete with SQLAlchemy models and tests","Database operations working with proper UTC timestamp handling","In-memory SQLite testing infrastructure proven effective"]}
-{"type":"entity","name":"Basic_Memory_Observation_Management_Design","entityType":"Design","observations":["Four approaches under consideration","Bulk Update: Simple but less efficient","Tracked Observations: Precise but clutters markdown","Diff-based: Efficient but complex","Position-based: Clean but fragile","Key challenge is balancing markdown readability with efficient updates","Must maintain filesystem as source of truth","Need to consider concurrent edits","Currently evaluating trade-offs","Implementation choice pending discussion"]}
-{"type":"entity","name":"Basic_Memory_Architectural_Decisions","entityType":"Decisions","observations":["Split file operations into separate fileio module","Using SQLAlchemy for database operations","Maintain filesystem as source of truth","Modular service-based architecture","Clear separation between data access and business logic","Repository pattern for database interactions","Schemas separate from models","Focus on maintainability and testability","Services handle business rules","Considering concurrency in design"]}
-{"type":"entity","name":"Basic_Memory_Implementation_Analysis","entityType":"Analysis","observations":["Clean modular architecture with clear responsibilities","Strong typing throughout codebase","Excellent error handling with custom exceptions","SQLAlchemy models perfectly match our domain model","Atomic file operations for data safety","Services implement filesystem-as-source-of-truth principle","Async support throughout","Good separation between domain models and database models","Careful handling of UTC timestamps","Smart use of SQLAlchemy relationships"]}
-{"type":"entity","name":"Basic_Memory_Current_Challenges","entityType":"Challenges","observations":["Observation update/removal strategy needs to be chosen","Need to handle concurrent file operations safely","Search functionality to be implemented","Edge cases in markdown formatting to be handled","Session management for concurrent operations needed","Balance between file operations and database sync","Testing coverage could be expanded","Need to handle relationship updates in files"]}
-{"type":"entity","name":"Basic_Memory_Observation_Hash_Tracking","entityType":"Design","observations":["Use content hashes to track observation identity","Store hashes in database but not in markdown","Can match observations across file edits using hashes","Similar to how git tracks content changes","Keeps markdown clean and human-friendly","Allows efficient bulk updates","Handles reordering of observations","Maintains filesystem as source of truth","No need for visible IDs in markdown","Could track observation history through hash changes"]}
-{"type":"entity","name":"Basic_Memory_Repository_Implementation","entityType":"Code_Implementation","observations":["Implemented base Repository class with CRUD operations","Added specialized EntityRepository, ObservationRepository, and RelationRepository","Used string IDs instead of UUIDs","Added UTCDateTime custom type for timestamp handling","Used in-memory SQLite for testing","Achieved 84% test coverage","Created comprehensive pytest fixtures"]}
-{"type":"entity","name":"Basic_Memory_Dependencies","entityType":"Technical","observations":["Uses Python 3.12","SQLAlchemy with async support","pytest-asyncio for async testing","aiosqlite for async SQLite operations","greenlet for SQLAlchemy async support","uv for dependency management","pytest-cov for coverage reporting","Development dependencies managed in pyproject.toml"]}
-{"type":"entity","name":"Basic_Memory_Current_Architecture","entityType":"Architecture_Analysis","observations":["Clear separation between domain models (Pydantic) and storage models (SQLAlchemy)","File I/O completely separated into dedicated module","Strong 'filesystem as source of truth' pattern in services","Atomic file operations with proper error handling","Service layer coordinates between filesystem and database","Database acts as queryable index rather than primary storage","Clean error hierarchy with specific exception types","Rebuild operations available for recovery scenarios"]}
-{"type":"entity","name":"Basic_Memory_Evolution","entityType":"Analysis","observations":["Started with repository pattern following basic-foundation","Evolved to more sophisticated architecture with clear layers","Added Pydantic schemas for domain modeling","Separated file operations into dedicated module","Implemented robust error handling throughout","Maintained filesystem as source of truth principle","Added observation management with context tracking","Introduced rebuild capabilities for system recovery"]}
-{"type":"entity","name":"Basic_Memory_Service_Layer","entityType":"Implementation","observations":["EntityService handles entity lifecycle and coordinates storage","ObservationService manages observations within entities","Services ensure filesystem and database stay in sync","Clear error handling with ServiceError hierarchy","Strong typing throughout service interfaces","Implements filesystem as source of truth pattern","Handles UUID generation and timestamp management","Provides methods for system recovery and rebuild"]}
-{"type":"entity","name":"Basic_Memory_Schema_Design","entityType":"Implementation","observations":["Uses Pydantic for domain models and validation","Automatic ID generation with timestamp and UUID","Clear separation from SQLAlchemy storage models","Supports optional context tracking","Models match markdown file structure","Enables clean serialization/deserialization","Strong typing with proper validation rules","Independent from storage concerns"]}
-{"type":"entity","name":"Basic_Memory_Next_Tasks","entityType":"TaskList","observations":["✅ Implement SQLAlchemy models and repositories (Done)","✅ Add SQLAlchemy migrations (Done)","✅ Create service layer (Done)","✅ Implement file I/O module (Done)","✅ Set up domain models with Pydantic (Done)","✅ Initial test infrastructure (Done)","✅ Basic CRUD operations (Done)","⏳ Implement full test coverage for db.py","⏳ Add more sophisticated search functionality","⏳ Implement CLI interface","⏳ Add relationship management to services","⏳ Handle concurrent file operations safely","⏳ Add versioning for file changes","⏳ Implement proper backup strategy","⏳ Add type hints throughout codebase","⏳ Improve error messages and logging","⏳ Add documentation for core modules"]}
-{"type":"entity","name":"Basic_Memory_Meta_Experience","entityType":"Case_Study","observations":["Experienced our own context loss when reconstructing project knowledge","Had to rebuild task list and project context from filesystem and memory","Validated 'filesystem as source of truth' principle through reconstruction","Code and tests served as reliable historical record","Knowledge graph structure helped guide reconstruction process","Markdown files provided human-readable context","Atomic information design made piece-by-piece reconstruction possible","Ironic validation of the need for basic-memory's features","Experience demonstrates value of durable, human-readable knowledge storage","Shows importance of separating durable storage from ephemeral context"]}
-{"type":"entity","name":"Model_Context_Protocol","entityType":"protocol","observations":["Core part of the basic-memory architecture","Enables AI-human collaboration on projects","Provides tool-based interaction with knowledge graph","Developed by Anthropic for structured AI-system interaction","Used for maintaining consistent, rich context across conversations"]}
-{"type":"entity","name":"basic-memory_core_principles","entityType":"principles","observations":["Local First: All data stored locally in SQLite","Project Isolation: Separate databases per project","Human Readable: Everything exportable to plain text","AI Friendly: Structure optimized for LLM interaction","DIY Ethics: User owns and controls their data","Simple Core: Start simple, expand based on needs","Tool Integration: MCP-based interaction model"]}
-{"type":"entity","name":"basic-memory_business_model","entityType":"business_strategy","observations":["Core features free: Local SQLite, basic knowledge graph, search, markdown export, basic MCP tools","Professional features potential: Rich document export, advanced versioning, collaboration features, custom integrations, priority support","Focus on maintaining DIY/punk philosophy while enabling sustainability"]}
-{"type":"entity","name":"basic-memory_cli","entityType":"interface","observations":["Supports project management commands (create, switch, list)","Entity management (add entity, add observation, add relation)","Future support for export and batch operations","Follows consistent command structure","Planned integration with MCP tools"]}
-{"type":"entity","name":"basic-memory_export_format","entityType":"file_format","observations":["Uses markdown with frontmatter metadata","Includes entity name, type, creation timestamp","Observations as bullet points","Relations in structured format with links","References section at bottom","Designed for human readability and machine parsing","Example format documented in project specs"]}
-{"type":"entity","name":"relation_service","entityType":"code_module","observations":["Planned service for managing relations in both filesystem and database","Will follow filesystem-is-source-of-truth principle like other services","Needs to handle atomic file operations for relation updates","Must coordinate with EntityService for relationship integrity","Will handle bidirectional relationship tracking","Will support relation validation and type enforcement","Must implement rebuild functionality for index recovery","Will need careful error handling for file/db sync","Should support relation search and filtering","Must handle relation lifecycle (create/read/update/delete)"]}
-{"type":"entity","name":"service_layer_patterns","entityType":"implementation_patterns","observations":["Services handle both file and database operations","Filesystem is always source of truth","Database serves as queryable index","Services implement atomic file operations","Clear error hierarchy with specific exceptions","Use of dependency injection via constructor params","Async/await used throughout service layer","Services coordinate between storage layers","Repository pattern used for database access","Services maintain entity integrity across storage","Rich error types extend from ServiceError base","Rebuild operations available for recovery"]}
-{"type":"entity","name":"database_models","entityType":"implementation","observations":["Entity model with unique name and type","Observation model linked to entities","Relation model tracks connections between entities","Custom UTCDateTime type for timestamp handling","Use of SQLAlchemy relationships for navigation","Cascading deletes for dependent objects","String IDs used for compatibility","Rich relationship modeling with backpopulates","Proper indexing on foreign keys","Context tracking available on models","Models include created_at timestamps","Relationships handle bidirectional navigation"]}
-{"type":"entity","name":"repository_patterns","entityType":"implementation_patterns","observations":["Generic Repository[T] base class implementation","Type-safe operations with SQLAlchemy","Specialized repositories for each model type","Async operations throughout","Clear error handling patterns","Support for custom queries and filtering","Pagination support built-in","Transaction management via session","Proper type hints and generics usage","Entity-specific query methods in subclasses"]}
-{"type":"entity","name":"relation_service_design","entityType":"design","observations":["Must handle relation lifecycle in both files and DB","Needs to validate existence of both entities","Should support relation type enforcement","Must maintain bidirectional consistency","Should support relation querying and filtering","Needs proper error handling for graph consistency","Must integrate with entity file format","Should support bulk operations for efficiency","Must handle relation deletion and cascading","Should provide search by type and entities"]}
-{"type":"entity","name":"relation_service_implementation_plan","entityType":"plan","observations":["1. Define core relation operations (create, get, delete)","2. Implement file format handling for relations","3. Add database sync with RelationRepository","4. Implement validation and error handling","5. Add rebuild and recovery operations","6. Implement relation type enforcement","7. Add relation search and filtering","8. Implement bulk operations","9. Add comprehensive tests","10. Document API and error handling"]}
-{"type":"entity","name":"relation_service_challenges","entityType":"challenges","observations":["Maintaining consistency between file and database","Handling relation type validation efficiently","Managing bidirectional relationships in files","Ensuring atomic updates across entities","Handling deletion with proper cascading","Efficient querying of relation graphs","Recovery from partial file/db sync failures","Bulk operation atomicity","Clear error reporting for graph operations","Performance with large relation sets"]}
-{"type":"entity","name":"relation_file_format","entityType":"file_format","observations":["Relations stored in entity markdown files","Format: [target_id] relation_type | context","Relations section marked by ## Relations header","Outgoing relations only stored in source entity","Relations rebuild on entity load","Clean human-readable format","Context is optional with pipe separator","Links generate valid navigation references","Markdown-friendly formatting","Example: [Paul] authored | with Claude"]}
-{"type":"entity","name":"relation_service_error_handling","entityType":"implementation_patterns","observations":["RelationError extends ServiceError base","Specific errors for validation failures","Handles entity not found cases","Manages relation type validation errors","File operation errors properly wrapped","Database sync errors clearly reported","Transaction rollback on errors","Proper error propagation chain","Clear error messages for debugging","Recovery paths for common errors"]}
-{"type":"entity","name":"relation_service_testing","entityType":"testing","observations":["Test all relation lifecycle operations","Verify file and database consistency","Test relation type validation","Check error handling paths","Test bulk operations","Verify bidirectional consistency","Test recovery operations","Check cascade operations","Verify search and filtering","Test with large relation sets"]}
-{"type":"entity","name":"fileio_patterns","entityType":"implementation_patterns","observations":["Atomic file operations with temporary files","Clear error handling for IO operations","Consistent file naming and paths","Support for different file formats","Efficient file reading and writing","Proper file locking mechanisms","Recovery from partial writes","Consistent encoding handling","Directory management utilities","Path manipulation helpers","Currently implemented in fileio.py module","Uses pathlib for path operations","Handles file not found cases gracefully","Maintains data integrity during writes"]}
-{"type":"entity","name":"pytest_patterns","entityType":"implementation_patterns","observations":["Common fixtures should be in conftest.py for reuse","Use pytest_asyncio.fixture for async fixtures","Session fixtures need proper async cleanup","Temporary directories should be managed with context managers","Test categories: happy path, error path, recovery, edge cases","Services need project_path and repo injected","Use monkeypatch for mocking in async context","SQLite in-memory database ideal for testing","Explicit test verification: file content and database state"]}
-{"type":"entity","name":"relation_implementation_learnings","entityType":"implementation_learnings","observations":["Better to pass full Entity objects than IDs to services","Services should not re-read entities if they have them","File operations should be atomic and verified","Database serves as queryable index, not source of truth","Relations stored in source entity's markdown file","Clear separation between file ops and database sync","Entity objects should own their relations list","Context is optional but fully supported in implementation"]}
-{"type":"entity","name":"test_driven_insights","entityType":"learnings","observations":["Tests help reveal better API design (e.g., passing Entity objects)","Error cases drive proper exception hierarchy","File verification as important as database checks","Edge cases inform markdown format decisions","Recovery tests ensure system resilience","Tests document expected behavior clearly","Fixtures significantly reduce test complexity","Common patterns emerge through test writing"]}
-{"type":"entity","name":"meta_development_insights","entityType":"process","observations":["Break down large tasks into reviewable chunks","One file at a time prevents response truncation","Iterative development with tests leads to better design","Infrastructure code (fixtures) should be consolidated early","Test categories help ensure comprehensive coverage","Knowledge capture should happen during development","APIs tend to evolve toward simpler patterns","File operations require careful verification"]}
-{"type":"entity","name":"AI_Assistant_Learnings","entityType":"meta_insights","observations":["Output management: Breaking responses into single files prevents truncation and allows better review","Knowledge graph helps maintain context: I can reference previous decisions and patterns accurately","Memory rebuilding experience validated the need for durable storage","Test-driven development provides clear steps and verification","Explicit relation tracking in knowledge graph helps me understand project context","Rich context from multiple sources (code, docs, tests) enables better assistance","File-at-a-time approach allows deeper analysis of each component","Keeping entity names consistent helps with referencing and relationships"]}
-{"type":"entity","name":"Effective_Response_Patterns","entityType":"meta_patterns","observations":["When showing code changes, break into discrete files","Review existing code before suggesting changes","Reference knowledge graph for context and patterns","Explicitly connect new code to existing patterns","Validate suggestions against test cases","Keep track of file changes for atomic commits","Check both implementation and test files for consistency","Maintain clear separation of concerns in responses"]}
-{"type":"entity","name":"AI_Context_Management","entityType":"meta_practice","observations":["Knowledge graph provides reliable persistent memory","Project documentation gives high-level context","Code review shows implementation patterns","Tests demonstrate expected behavior","Important to actively track what has been modified","Entity relationships help understand dependencies","Regular knowledge capture during development","Using consistent entity references across conversations"]}
-{"type":"entity","name":"AI_Tool_Usage_Patterns","entityType":"meta_practice","observations":["read_file before suggesting changes","write_file one file at a time","list_directory to understand project structure","search_nodes to find relevant context","create_entities to capture new learnings","create_relations to connect concepts","Using knowledge graph to track decisions","Validating changes through test execution"]}
-{"type":"entity","name":"relation_service_learnings","entityType":"implementation_learnings","observations":["Entity-based API cleaner than ID-based for service layer","Model_dump method can handle storage serialization","File format needs explicit section markers (## Relations)","Whitespace handling important for long content comparisons","Test fixtures allow focused test cases","SQLAlchemy selects better than raw SQL for type safety","Atomic file operations maintained for relations"]}
-{"type":"entity","name":"test_driven_insights_relations","entityType":"learnings","observations":["Tests revealed need for whitespace normalization","Edge cases drove file format decisions","SQLAlchemy model access safer than raw queries","Fixtures reduced test setup complexity","File verification as important as database checks","Testing both memory model and storage format","Test categories ensure comprehensive coverage"]}
-{"type":"entity","name":"relation_service_patterns","entityType":"patterns","observations":["Use Entity objects in API","Serialize to IDs for storage","Maintain file as source of truth","Keep file format human-readable","Handle circular references in serialization","Use repository pattern for database","Clear error hierarchies"]}
-{"type":"entity","name":"packaging_learnings","entityType":"technical_learnings","observations":["When using pytest-mock, traditional pip install works more reliably than uv sync","Package discovery behavior can differ between uv and pip","Clean venv with pip install is a reliable fallback for dependency issues","Package installation location might differ between uv and pip","Dependencies in pyproject.toml dev section work reliably with pip install -e .[dev]"]}
-{"type":"entity","name":"Recent_Implementation_Progress","entityType":"progress_update","observations":["Successfully split services.py into modular structure under services/","Created __init__.py, entity_service.py, observation_service.py, relation_service.py","Fixed pytest-mock installation issues by using pip install -e .[dev] instead of uv sync","Improved test structure with minimal mocking - only used for error testing","Implemented relation service with Entity-based API","Achieved good test coverage across services","File operations are only mocked when testing error conditions","Services follow filesystem-as-source-of-truth pattern"]}
-{"type":"entity","name":"Next_Steps","entityType":"project_tasks","observations":["Consider adding more relation service tests","Potentially expand relations features","Look for opportunities to improve test coverage","Consider documenting package management preferences (pip vs uv)","Consider adding integration tests for services","Review and possibly expand error handling cases"]}
-{"type":"entity","name":"Development_Practices","entityType":"process","observations":["Favor real operations over mocks in tests","Only mock for error condition testing","Use pip install -e .[dev] for reliable dev dependency installation","Maintain modular service structure","Keep filesystem as source of truth","Use Entity objects in service APIs instead of IDs","Validate both file and database state in tests"]}
-{"type":"entity","name":"MCP_Resources","entityType":"Concept","observations":["Stateful objects in Model Context Protocol","Enable persistent access to capabilities"]}
-{"type":"entity","name":"MCP_Server_Implementation","entityType":"Technical_Design","observations":["Inherits from mcp.server.Server base class","Tools are implemented as async methods","Each tool method maps directly to a function available to the AI","Tools can request user input via Prompts","Simple function call interface rather than explicit resource management","State management handled by server instance","Returns serialized data using model_dump() for consistency"]}
-{"type":"entity","name":"MCP_Tools","entityType":"Protocol_Feature","observations":["Defined as async methods on server class","Return values must match tool definition schema","Can maintain state between invocations via server instance","Tools can prompt for user input when needed","No need for explicit Resource objects in implementation"]}
-{"type":"entity","name":"Basic_Memory_MCP","entityType":"Implementation","observations":["Uses MemoryService for core operations","Implements project selection via prompts","Maintains project context across tool invocations","Maps directly to memory graph operations","Handles serialization of Pydantic models"]}
-{"type":"entity","name":"Basic_Memory_Testing","entityType":"Testing_Design","observations":["Needs pytest for async testing","Should isolate filesystem operations for tests","Needs to handle MCP server lifecycle in tests","Should test both service layer and MCP interface","Will need mocks for project paths and file operations"]}
-{"type":"entity","name":"Memory_Service_Tests","entityType":"Test_Suite","observations":["Should test entity creation with observations","Should test relation creation between entities","Should verify proper ID generation and model validation","Should test deletion cascading","Should test search functionality","Must verify proper serialization of entities and relations"]}
-{"type":"entity","name":"MCP_Server_Tests","entityType":"Test_Suite","observations":["Should test project initialization workflow","Should test prompt handling","Should verify tool input/output formats","Should test error cases and validation","Must verify proper serialization in tool responses"]}
-{"type":"entity","name":"Memory_Service_Refactoring","entityType":"Technical_Task","observations":["MemoryService uses create() but EntityService might expect create_entity()","MemoryService assumes get_by_name() but EntityService might use different method","Need to verify deletion method signatures","Need to check if search interface matches","Should verify observation handling matches ObservationService interface","RelationService methods need verification","EntityService.create_entity takes name, type, and optional observations directly, not an Entity object","EntityService requires project_path and entity_repo in constructor","ObservationService.add_observation takes Entity object and content string, not raw data","RelationService.create_relation takes Entity objects directly, not dict data","All services follow filesystem-as-source-of-truth pattern with DB indexing","All services handle database synchronization internally","Services expect Path objects for filesystem operations"]}
-{"type":"entity","name":"Service_Interface_Audit","entityType":"Technical_Task","observations":["Need to review all existing service interfaces","Document current method signatures","Map discrepancies between MemoryService assumptions and actual interfaces","Check return types and error handling patterns","Review transaction/atomicity requirements","Method signatures need alignment: create vs create_entity etc","Need to handle DB repositories in service constructors","File operations should use project_path consistently","Need to maintain filesystem-as-source-of-truth pattern","Should handle database synchronization at service level","Error handling should align with existing patterns","Consider making MemoryService handle DB indexing consistently"]}
-{"type":"entity","name":"Memory_Service_Patterns","entityType":"Technical_Pattern","observations":["Uses inner async functions to encapsulate operation logic","Leverages list comprehensions with async functions for parallel operations","Each operation follows a consistent pattern: validate, update DB, write file","Inner functions make the code more readable and maintainable","Operations can run in parallel when using list comprehensions with async functions"]}
-{"type":"entity","name":"Pydantic_Create_Pattern","entityType":"Technical_Pattern","observations":["Separate Create models match the exact shape of incoming data","Provides clear contract for MCP tool inputs","Handles validation of raw input data","Converts cleanly to domain models via from_create methods","Maintains separation between external API format and internal models","Similar to FastAPI request model pattern","Allows camelCase in API while using snake_case internally"]}
-{"type":"entity","name":"Basic_Memory_Business","entityType":"Business_Model","observations":["Core system is open source and free","Local-first, giving users data control","Professional features could be licensed","Enterprise support and customization services","Potential for MCP tool marketplace"]}
-{"type":"entity","name":"MCP_Marketplace","entityType":"Business_Concept","observations":["Could host verified MCP tools for different use cases","Tools rated by performance and reliability","Marketplace takes percentage of tool usage fees","Enterprise tool verification and security scanning","Custom tool development services","Integration support for existing tools"]}
-{"type":"entity","name":"Persistence_Of_Vision","entityType":"Concept","observations":["Mental model for continuous AI-human interaction","Like cinema: 24fps creates illusion of smooth motion","Basic-memory provides 'frames' of structured knowledge","Current state: Better than flipbook, not yet digital cinema","Goal: Achieve smoother cognitive continuity between interactions","Proposed by Drew as metaphor for AI conversation continuity"]}
-{"type":"entity","name":"Conversation_Continuity_Pattern","entityType":"Usage_Pattern","observations":["Use basic-memory entity/relation schema for conversations","Each chat becomes an entity with observations for key points","Relations link to discussed concepts and other chats","Uses zettelkasten format IDs for natural ordering","Can be used as template/recipe for others","Future possibility: Git SHA integration for versioning"]}
-{"type":"entity","name":"Usage_Recipes","entityType":"Feature_Concept","observations":["Predefined patterns users can follow or adapt","Could include conversation tracking recipe","Templates for different knowledge management styles","Shows practical applications of the generic schema","Helps users get started with the system"]}
-{"type":"entity","name":"Chat_References","entityType":"Technical_Feature","observations":["Uses ref:* syntax to reference previous conversations","Combines reference semantics with pointer symbolism","Format: ref:*{zettelkasten-id}","Allows explicit context loading between chats","Inspired by C++ references and pointers","Provides memory-model-like access to conversation context","Uses ref:// URI format following MCP Resource pattern","Could support multiple reference schemes (chat/entity/concept)","Makes reference semantics explicit and unambiguous","Aligns with standard URI formatting"]}
-{"type":"entity","name":"Chat_Reference_Protocol","entityType":"Technical_Specification","observations":["Uses URI format: ref://basic-memory/chat/[id]","Follows MCP Resource pattern: [protocol]://[host]/[path]","Enables explicit context loading between chats","Can support multiple resource types (chat/entity/concept)","Provides standardized way to reference previous conversations","Example: ref://basic-memory/chat/20240307-drew-ab12ef34"]}
-{"type":"entity","name":"20240307-chat-reference-protocol","entityType":"conversation","observations":["Developed ref:// URI format for chat references","Added Chat Reference Protocol to prompt instructions","Discussed implementation of chat continuation","Created complete prompt instructions document","Reference format follows MCP Resource pattern","Reviewed and confirmed complete prompt instructions","Ready to test ref://basic-memory/chat/20240307-chat-reference-protocol in new chat"]}
-{"type":"entity","name":"20240307-chat-reference-protocol-test","entityType":"conversation","observations":["First implementation test of chat reference protocol","Testing continuation from 20240307-chat-reference-protocol","Focused on practical implementation of ref:// URI format"]}
-{"type":"entity","name":"Write_File_Tool_Usage","entityType":"Tool_Usage_Pattern","observations":["Never use placeholders like '# Rest of...' when writing files - must include complete file content","File content must be complete and valid - partial updates will truncate the file","If showing partial changes, should inform human and let them handle the file write","write_file tool replaces entire file contents - cannot do partial updates","Code files especially must be complete and valid to avoid breaking functionality","Always read_file before write_file to understand current state","Using write_file without reading first risks reverting recent changes","Pattern should be: read current state, make modifications, then write if needed","Especially important in collaborative development where files may have been updated"]}
-{"type":"entity","name":"Run_Tests_Tool_Request","entityType":"Feature_Request","observations":["Need to add a tool enabling Claude to run tests locally","Would help with direct validation of code changes","Current workaround: Claude has to ask human to run tests","Should support running specific test functions (e.g. pytest tests/test_memory_service.py::test_create_relations)","Would improve iterative development workflow between human and AI"]}
-{"type":"entity","name":"SQLAlchemy_Async_Loading_Pattern","entityType":"Technical_Pattern","observations":["Use selectinload() instead of lazy loading when accessing SQLAlchemy relationships in async code","Lazy loading doesn't work with async due to greenlet context requirements","selectinload performs a single efficient query with an IN clause","Pattern used in basic-memory's EntityRepository for loading relations","Documented in find_by_id method with thorough explanation","Alternative approaches: joinedload (single JOIN query) or subqueryload (subquery approach)","Benefits: prevents 'MissingGreenlet' errors, reduces N+1 query problems","Key insight: load all needed relationships upfront in async code","Example use: selectinload(Entity.outgoing_relations)"]}
-{"type":"entity","name":"20241207-sqlalchemy-async-pattern","entityType":"conversation","observations":["Fixed SQLAlchemy async relationship loading issues","Implemented selectinload pattern in EntityRepository","Updated find_by_id to eager load relations","Added documentation about the pattern","Created knowledge graph entry about SQLAlchemy async loading","Fixed failing tests by properly loading relations in memory_service","Discussed SQLAlchemy relationship loading best practices"]}
-{"type":"entity","name":"20241207-memory-service-relations","entityType":"conversation","observations":["Fixed SQLAlchemy async loading with selectinload pattern","Updated find_by_id in EntityRepository to eager load relations","Discovered create_relations works but returns empty list","Verified relations are being stored correctly in memory.json","Next step: Work on MemoryService.add_observations implementation","Improved understanding of MCP memory storage format through debugging"]}
-{"type":"entity","name":"add_observations_implementation_plan","entityType":"technical_plan","observations":["Follow pattern from create_entity and create_relation methods","File operations first (read & write) - filesystem is source of truth","Database updates in parallel","Simplify current implementation","Current flow is:"," - First read entities and create observations"," - Write files in parallel"," - Update DB indexes sequentially","Key tests needed:"," - Adding observations to multiple entities"," - Verifying filesystem state first"," - Verifying database state"," - Error cases for missing entities"," - Error cases for file operations"]}
-{"type":"entity","name":"MCP_Reference_Integration","entityType":"feature_idea","observations":["Can be implemented as a Model Context Protocol integration similar to the fetch tool","Would provide structured way to pass chat references to Claude","Could handle ref:// URL format systematically","Integration would fetch context from referenced chats and inject into conversation","Observed from Claude Desktop UI showing MCP integration pattern with fetch tool","Would be more robust than passing references in chat text"]}
-{"type":"entity","name":"Project_Priorities","entityType":"roadmap","observations":["P1: Dogfooding basic-memory system instead of JSON memory store","Future: Implement MCP-based reference system"]}
-{"type":"entity","name":"great_observation_loading_saga_20241207","entityType":"debugging_session","observations":["Occurred on December 7, 2024 while debugging basic-memory SQLAlchemy relationship loading","Issue: selectinload() wasn't properly loading relationships in async SQLAlchemy context","Tried multiple solutions: explicit joins, manual loading, various SQLAlchemy loading strategies","Final solution: Using session.refresh() with explicit relationship names","Memorable quote: 'The Great Observation Loading Saga'","Key learning: Sometimes the obvious SQLAlchemy patterns need adaptation for async contexts","Solution preserved in basic-memory repository in EntityRepository.find_by_id()"]}
-{"type":"entity","name":"basic_memory_implementation_20241208","entityType":"technical_milestone","observations":["Fixed async SQLAlchemy relationship loading issues by using explicit refresh with relationship names","Established pattern of relationship handling belonging in MemoryService not EntityService","Fixed ID generation flow through Pydantic schemas to DB layer","Standardized error handling using EntityNotFoundError","All 32 tests passing with 70% coverage","Core services (Entity, Observation, Relation) working properly","Ready for MCP server implementation","Notable debugging session: The Great Observation Loading Saga - resolved lazy loading issues","Established clear separation between MemoryService orchestration and individual service responsibilities"]}
-{"type":"entity","name":"MCP_Dependency_Risk","entityType":"technical_lesson","observations":["Experienced disruption when MCP npm package disappeared - 'leftpad moment'","Need to ensure basic-memory tools are resilient to external dependency issues","Local implementation of MCP server provides better stability than npm packages","Important to maintain control of critical infrastructure components","Validates DIY/local-first philosophy of basic-memory project","Package manager fragility revealed by simple 'npx @modelcontextprotocol/server-memory' failure"]}
-{"type":"entity","name":"basic_memory_project_20241208","entityType":"technical_milestone","observations":["Core MCP server implementation completed with tools: create_entities, search_nodes, open_nodes, add_observations, create_relations, delete_entities, delete_observations","ProjectConfig and dependency injection pattern established","Test framework in place with in-memory DB support","Support for both camelCase (MCP) and snake_case (internal) formats","Filesystem remains source of truth with SQLite as index","Two-way sync pattern identified between Claude MCP tools and direct markdown file editing","Ready for Claude Desktop integration testing phase","Next steps identified: passing tests, markdown format definition, file change tracking, real-world testing","Implementation prioritizes local-first principles with filesystem as source of truth"]}
-{"type":"entity","name":"basic_memory_mcp_architecture","entityType":"technical_design","observations":["MemoryServer class extends MCP Server with custom handler registration","Uses ProjectConfig for clean dependency injection and configuration","Memory service can be injected for testing","Handlers exposed as instance attributes for testing","Tool schemas leverage existing Pydantic models"]}
-{"type":"entity","name":"basic_memory_sync_considerations","entityType":"design_insight","observations":["Need to handle sync between direct markdown file edits and DB index","Watch for file system changes as potential future enhancement","Consider index rebuild patterns on startup","Keep human-friendly markdown format for direct editing"]}
-{"type":"entity","name":"mcp_server_learnings","entityType":"developer_insight","observations":["MCP protocol is new and documentation is still evolving","Test patterns are not well established yet in example implementations","Supporting both camelCase and snake_case helps with protocol/internal compatibility","Server.handle_* naming convention is important for handler registration"]}
-{"type":"entity","name":"20241208-mcp-tool-refactoring","entityType":"conversation","observations":["Decision to return structured data via EmbeddedResource instead of TextContent string parsing","Plan to create Pydantic result models (CreateEntitiesResult, SearchNodesResult etc)","Will use application/vnd.basic-memory+json as MIME type for our structured data","Currently debugging test issues with add_observations tool","Entity ID vs name resolution needed in add_observations","Goal is to make tools more joyful to use by eliminating string parsing","MCP spec supports EmbeddedResource for structured data returns"]}
-{"type":"entity","name":"Basic Memory MCP Server Implementation","entityType":"technical_notes","observations":["Server implements Model Context Protocol using proper structured data responses","Uses EmbeddedResource with custom MIME type 'application/vnd.basic-memory+json'","Clean separation between input validation and handlers via Pydantic models","All tool operations return structured data through create_response helper","Type safety with Literal types for tool names and proper typing for handlers","Handler registry pattern with TOOL_HANDLERS dictionary","Consistent error handling pattern using MCP error codes","Uses Pydantic ConfigDict for proper ORM integration","Tool schemas organized into Input and Response types","Input validation with Annotated types for extra constraints","Response models consistently use from_attributes=True for ORM data","Entity ID generation moved to model validator on EntityBase","Follows principle of making common operations easy and safe"]}
-{"type":"relation","from":"Paul","to":"Basic_Machines","relationType":"created_and_maintains"}
-{"type":"relation","from":"basic-memory","to":"Basic_Machines","relationType":"is_component_of"}
-{"type":"relation","from":"Paul","to":"basic-memory","relationType":"develops"}
-{"type":"relation","from":"fileio_module","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"entity_service","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"observation_service","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"fileio_module","to":"basic-memory","relationType":"is_component_of"}
-{"type":"relation","from":"entity_service","to":"basic-memory","relationType":"is_component_of"}
-{"type":"relation","from":"observation_service","to":"basic-memory","relationType":"is_component_of"}
-{"type":"relation","from":"entity_service","to":"fileio_module","relationType":"uses"}
-{"type":"relation","from":"observation_service","to":"fileio_module","relationType":"uses"}
-{"type":"relation","from":"observation_management","to":"observation_service","relationType":"influences_design_of"}
-{"type":"relation","to":"basic-memory","from":"testing_infrastructure","relationType":"supports"}
-{"type":"relation","to":"testing_infrastructure","from":"test_categories","relationType":"implements"}
-{"type":"relation","to":"basic-memory","from":"completed_work","relationType":"tracks_progress_of"}
-{"type":"relation","to":"basic-memory","from":"future_work","relationType":"guides_development_of"}
-{"type":"relation","to":"basic-memory","from":"design_decisions","relationType":"shapes_architecture_of"}
-{"type":"relation","to":"basic-memory","from":"concurrency_considerations","relationType":"influences_design_of"}
-{"type":"relation","to":"future_work","from":"concurrency_considerations","relationType":"informs"}
-{"type":"relation","to":"observation_management","from":"design_decisions","relationType":"guides"}
-{"type":"relation","to":"testing_infrastructure","from":"completed_work","relationType":"established"}
-{"type":"relation","to":"design_decisions","from":"fileio_module","relationType":"implements"}
-{"type":"relation","from":"observation_update_approaches","to":"observation_management","relationType":"analyzes"}
-{"type":"relation","from":"bulk_update_approach","to":"observation_update_approaches","relationType":"is_option_of"}
-{"type":"relation","from":"tracked_observations_approach","to":"observation_update_approaches","relationType":"is_option_of"}
-{"type":"relation","from":"diff_based_approach","to":"observation_update_approaches","relationType":"is_option_of"}
-{"type":"relation","from":"position_based_approach","to":"observation_update_approaches","relationType":"is_option_of"}
-{"type":"relation","from":"tasks_and_progress","to":"basic-memory","relationType":"tracks_status_of"}
-{"type":"relation","from":"design_decisions","to":"observation_update_approaches","relationType":"influences"}
-{"type":"relation","from":"observation_update_approaches","to":"future_work","relationType":"informs"}
-{"type":"relation","to":"basic-memory_implementation_patterns","from":"error_handling_patterns","relationType":"is_part_of"}
-{"type":"relation","to":"basic-memory","from":"data_models","relationType":"implements"}
-{"type":"relation","to":"basic-memory","from":"markdown_format","relationType":"defines"}
-{"type":"relation","to":"basic-memory","from":"test_driven_development","relationType":"guides_development_of"}
-{"type":"relation","to":"basic-memory","from":"architecture_evolution","relationType":"describes_development_of"}
-{"type":"relation","to":"basic-memory_implementation_patterns","from":"validation_patterns","relationType":"is_part_of"}
-{"type":"relation","to":"design_decisions","from":"architecture_evolution","relationType":"informs"}
-{"type":"relation","to":"fileio_module","from":"markdown_format","relationType":"implements"}
-{"type":"relation","to":"error_handling_patterns","from":"test_driven_development","relationType":"influenced"}
-{"type":"relation","to":"data_models","from":"validation_patterns","relationType":"implements"}
-{"type":"relation","to":"markdown_format","from":"markdown_examples","relationType":"documents"}
-{"type":"relation","to":"markdown_format","from":"markdown_parsing_rules","relationType":"defines"}
-{"type":"relation","to":"data_models","from":"schema_definitions","relationType":"documents"}
-{"type":"relation","to":"test_driven_development","from":"test_evolution","relationType":"describes"}
-{"type":"relation","to":"architecture_evolution","from":"implementation_challenges","relationType":"influenced"}
-{"type":"relation","to":"test_evolution","from":"implementation_challenges","relationType":"shaped"}
-{"type":"relation","to":"future_work","from":"implementation_challenges","relationType":"informs"}
-{"type":"relation","from":"Basic_Factory","to":"Basic_Machines","relationType":"implements"}
-{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Factory","relationType":"is_part_of"}
-{"type":"relation","from":"Component_Translation_Process","to":"Basic_Factory_Components","relationType":"enables"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines","relationType":"guides"}
-{"type":"relation","from":"Paul","to":"Basic_Factory","relationType":"develops"}
-{"type":"relation","from":"Paul","to":"Basic_Machines_Philosophy","relationType":"created"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Machines_Philosophy","relationType":"articulates"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Factory","relationType":"guides_development_of"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Paul","relationType":"written_by"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Component_Translation_Process","relationType":"documents"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Machines","relationType":"shapes_development_of"}
-{"type":"relation","from":"Basic_Machines_Roadmap","to":"Basic_Machines","relationType":"guides_development_of"}
-{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Machines_Roadmap","relationType":"implements_phase_of"}
-{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Machines_Website","relationType":"enables"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines_Website","relationType":"informs"}
-{"type":"relation","from":"Paul","to":"DIY_Ethics","relationType":"embodies"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"DIY_Ethics","relationType":"incorporates"}
-{"type":"relation","from":"Basic_Machines","to":"DIY_Ethics","relationType":"exemplifies"}
-{"type":"relation","from":"Component_Translation_Process","to":"Basic_Machines_Philosophy","relationType":"implements"}
-{"type":"relation","from":"Basic_Factory_Components","to":"DIY_Ethics","relationType":"demonstrates"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Machines_Philosophy","relationType":"aligns_with"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Component_Translation_Process","relationType":"guides"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Machines","relationType":"defines_vision_for"}
-{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Machines_Manifesto","relationType":"implements_vision_of"}
-{"type":"relation","from":"Basic_Factory","to":"AI_Human_Collaboration_Model","relationType":"demonstrates"}
-{"type":"relation","from":"Paul","to":"AI_Human_Collaboration_Model","relationType":"developed_with_Claude"}
-{"type":"relation","from":"Basic_Factory_Components","to":"Component_Translation_Process","relationType":"created_through"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Factory","relationType":"guides"}
-{"type":"relation","from":"Basic_Factory","to":"MCP_Tools","relationType":"integrates"}
-{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Factory_Components","relationType":"will_use"}
-{"type":"relation","from":"Basic_Machines_Roadmap","to":"Basic_Machines_Philosophy","relationType":"aligns_with"}
-{"type":"relation","from":"Component_Translation_Process","to":"MCP_Tools","relationType":"leverages"}
-{"type":"relation","from":"Basic_Factory","to":"basic-memory","relationType":"will_document_process_in"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"basic-memory","relationType":"will_be_implemented_in"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines_Roadmap","relationType":"informs_priorities_of"}
-{"type":"relation","from":"basic-memory","to":"Basic_Machines_Philosophy","relationType":"embodies"}
-{"type":"relation","from":"Paul","to":"Basic_Machines_Manifesto","relationType":"authored_with_Claude"}
-{"type":"relation","from":"Basic_Factory","to":"Component_Translation_Process","relationType":"validated"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"MCP_Tools","relationType":"utilizes"}
-{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Machines_Roadmap","relationType":"supports"}
-{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Factory","relationType":"will_demonstrate"}
-{"type":"relation","from":"Basic_Factory","to":"basic-memory-webui","relationType":"enables_development_of"}
-{"type":"relation","from":"basic-memory","to":"AI_Human_Development_Methodology","relationType":"implements"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"AI_Human_Development_Methodology","relationType":"guides"}
-{"type":"relation","from":"Basic_Factory_Components","to":"basic-memory-webui","relationType":"provides_ui_for"}
-{"type":"relation","from":"Component_Translation_Process","to":"AI_Human_Development_Methodology","relationType":"exemplifies"}
-{"type":"relation","from":"Basic_Factory","to":"Basic Components","relationType":"enabled_creation_of"}
-{"type":"relation","from":"Basic_Factory","to":"Tool Integration Discovery","relationType":"led_to"}
-{"type":"relation","from":"MCP_Integration_Progress","to":"AI_Human_Development_Methodology","relationType":"validates"}
-{"type":"relation","from":"Basic_Factory","to":"MCP_Integration_Progress","relationType":"demonstrates"}
-{"type":"relation","from":"Basic_Factory","to":"AI_Human_Development_Methodology","relationType":"proves_effectiveness_of"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic Components","relationType":"inspires_architecture_of"}
-{"type":"relation","from":"DIY_Ethics","to":"basic-memory","relationType":"shapes_design_of"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Tool Integration Discovery","relationType":"guides_analysis_of"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"AI_Human_Development_Methodology","relationType":"documents_approach_of"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Factory_Components","relationType":"explains_principles_of"}
-{"type":"relation","from":"Basic_Memory_Project_Structure","to":"basic-memory","relationType":"organizes"}
-{"type":"relation","from":"Basic_Memory_Database_Schema","to":"basic-memory","relationType":"defines_storage_for"}
-{"type":"relation","from":"Basic_Memory_Markdown_Example","to":"Basic_Memory_File_Format","relationType":"demonstrates"}
-{"type":"relation","from":"Basic_Memory_Project_Isolation_Decision","to":"Basic_Memory_Future_Enhancement_Weighted_Relations","relationType":"similar_to"}
-{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Project_Isolation_Decision","relationType":"follows"}
-{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"basic-memory","relationType":"guides"}
-{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"DIY_Ethics","relationType":"follows"}
-{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"Basic_Memory_Database_Schema","relationType":"implements"}
-{"type":"relation","from":"Basic_Memory_Implementation_Status","to":"Basic_Memory_Implementation_Plan","relationType":"updates"}
-{"type":"relation","from":"Basic_Memory_Observation_Management_Design","to":"Basic_Memory_Technical_Design","relationType":"extends"}
-{"type":"relation","from":"Basic_Memory_Architectural_Decisions","to":"DIY_Ethics","relationType":"guided_by"}
-{"type":"relation","from":"Basic_Memory_Architectural_Decisions","to":"basic-memory","relationType":"structures"}
-{"type":"relation","from":"Basic_Memory_Implementation_Status","to":"basic-memory","relationType":"describes_state_of"}
-{"type":"relation","to":"Basic_Memory_Implementation_Status","from":"Basic_Memory_Implementation_Analysis","relationType":"analyzes"}
-{"type":"relation","to":"basic-memory","from":"Basic_Memory_Current_Challenges","relationType":"identifies_issues_in"}
-{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Implementation_Analysis","relationType":"confirms_alignment_with"}
-{"type":"relation","to":"Basic_Memory_Observation_Management_Design","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"solves"}
-{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"aligns_with"}
-{"type":"relation","to":"Basic_Memory_File_Format","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"preserves"}
-{"type":"relation","to":"Basic_Memory_Technical_Design","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"enhances"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"basic-memory","relationType":"implements_part_of"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"Basic_Memory_Database_Schema","relationType":"follows"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"DIY_Ethics","relationType":"aligns_with"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"testing_infrastructure","relationType":"demonstrates"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"Basic Foundation","relationType":"inspired_by"}
-{"type":"relation","from":"Basic_Memory_Dependencies","to":"basic-memory","relationType":"supports"}
-{"type":"relation","from":"Basic_Memory_Dependencies","to":"Basic_Memory_Repository_Implementation","relationType":"enables"}
-{"type":"relation","from":"Basic_Memory_Dependencies","to":"testing_infrastructure","relationType":"enables"}
-{"type":"relation","from":"Basic_Memory_Current_Architecture","to":"basic-memory","relationType":"describes_state_of"}
-{"type":"relation","from":"Basic_Memory_Evolution","to":"Basic_Memory_Current_Architecture","relationType":"explains_development_of"}
-{"type":"relation","from":"Basic_Memory_Service_Layer","to":"Basic_Memory_Current_Architecture","relationType":"implements"}
-{"type":"relation","from":"Basic_Memory_Schema_Design","to":"Basic_Memory_Current_Architecture","relationType":"implements"}
-{"type":"relation","from":"Basic_Memory_Evolution","to":"Basic_Memory_Implementation_Plan","relationType":"reflects_on"}
-{"type":"relation","from":"Basic_Memory_Evolution","to":"DIY_Ethics","relationType":"demonstrates_alignment_with"}
-{"type":"relation","from":"Basic_Memory_Current_Architecture","to":"DIY_Ethics","relationType":"embodies"}
-{"type":"relation","from":"Basic_Memory_Service_Layer","to":"fileio_module","relationType":"uses"}
-{"type":"relation","from":"Basic_Memory_Schema_Design","to":"markdown_format","relationType":"implements"}
-{"type":"relation","to":"basic-memory","from":"Basic_Memory_Next_Tasks","relationType":"guides_development_of"}
-{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Next_Tasks","relationType":"aligns_with"}
-{"type":"relation","to":"Basic_Memory_Current_Architecture","from":"Basic_Memory_Next_Tasks","relationType":"extends"}
-{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"basic-memory","relationType":"validates_design_of"}
-{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"DIY_Ethics","relationType":"demonstrates_principles_of"}
-{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"design_decisions","relationType":"reinforces"}
-{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"Basic_Memory_Current_Architecture","relationType":"validates"}
-{"type":"relation","from":"Model_Context_Protocol","to":"basic-memory","relationType":"enables"}
-{"type":"relation","from":"basic-memory_core_principles","to":"basic-memory","relationType":"guides"}
-{"type":"relation","from":"basic-memory_core_principles","to":"DIY_Ethics","relationType":"aligns_with"}
-{"type":"relation","from":"basic-memory_business_model","to":"basic-memory","relationType":"defines_sustainability_for"}
-{"type":"relation","from":"basic-memory_business_model","to":"DIY_Ethics","relationType":"maintains_alignment_with"}
-{"type":"relation","from":"basic-memory_cli","to":"basic-memory","relationType":"provides_interface_for"}
-{"type":"relation","from":"basic-memory_cli","to":"Model_Context_Protocol","relationType":"integrates_with"}
-{"type":"relation","from":"basic-memory_export_format","to":"basic-memory","relationType":"standardizes_output_of"}
-{"type":"relation","from":"basic-memory_export_format","to":"markdown_format","relationType":"extends"}
-{"type":"relation","from":"basic-memory_core_principles","to":"Basic_Machines_Philosophy","relationType":"implements"}
-{"type":"relation","from":"Model_Context_Protocol","to":"AI_Human_Collaboration_Model","relationType":"enables"}
-{"type":"relation","from":"relation_service","to":"basic-memory","relationType":"will_be_component_of"}
-{"type":"relation","from":"relation_service","to":"service_layer_patterns","relationType":"follows"}
-{"type":"relation","from":"relation_service","to":"fileio_patterns","relationType":"uses"}
-{"type":"relation","from":"relation_service","to":"database_models","relationType":"uses"}
-{"type":"relation","from":"relation_service","to":"repository_patterns","relationType":"implements"}
-{"type":"relation","from":"relation_service_design","to":"relation_service","relationType":"guides_implementation_of"}
-{"type":"relation","from":"relation_service_implementation_plan","to":"relation_service","relationType":"defines_implementation_of"}
-{"type":"relation","from":"relation_service_challenges","to":"relation_service_design","relationType":"informs"}
-{"type":"relation","from":"relation_file_format","to":"markdown_format","relationType":"extends"}
-{"type":"relation","from":"relation_service_error_handling","to":"service_layer_patterns","relationType":"implements"}
-{"type":"relation","from":"relation_service_testing","to":"testing_infrastructure","relationType":"extends"}
-{"type":"relation","from":"fileio_patterns","to":"service_layer_patterns","relationType":"enables"}
-{"type":"relation","from":"database_models","to":"repository_patterns","relationType":"enables"}
-{"type":"relation","from":"relation_service","to":"entity_service","relationType":"coordinates_with"}
-{"type":"relation","from":"relation_file_format","to":"relation_service","relationType":"defines_storage_for"}
-{"type":"relation","from":"relation_service_error_handling","to":"relation_service","relationType":"ensures_reliability_of"}
-{"type":"relation","from":"relation_service_testing","to":"relation_service","relationType":"verifies"}
-{"type":"relation","from":"service_layer_patterns","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"repository_patterns","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"fileio_patterns","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"database_models","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"relation_service_challenges","to":"implementation_challenges","relationType":"extends"}
-{"type":"relation","from":"relation_service_implementation_plan","to":"future_work","relationType":"details"}
-{"type":"relation","from":"relation_service_design","to":"design_decisions","relationType":"aligns_with"}
-{"type":"relation","from":"relation_file_format","to":"design_decisions","relationType":"follows"}
-{"type":"relation","from":"pytest_patterns","to":"testing_infrastructure","relationType":"extends"}
-{"type":"relation","from":"relation_implementation_learnings","to":"basic-memory_implementation_patterns","relationType":"informs"}
-{"type":"relation","from":"test_driven_insights","to":"test_driven_development","relationType":"enriches"}
-{"type":"relation","from":"meta_development_insights","to":"AI_Human_Collaboration_Model","relationType":"improves"}
-{"type":"relation","from":"relation_implementation_learnings","to":"relation_service","relationType":"guides_implementation_of"}
-{"type":"relation","from":"pytest_patterns","to":"test_evolution","relationType":"demonstrates"}
-{"type":"relation","from":"test_driven_insights","to":"design_decisions","relationType":"influences"}
-{"type":"relation","from":"meta_development_insights","to":"architecture_evolution","relationType":"informs"}
-{"type":"relation","from":"relation_service","to":"relation_implementation_learnings","relationType":"validates"}
-{"type":"relation","from":"test_driven_insights","to":"implementation_challenges","relationType":"helps_solve"}
-{"type":"relation","from":"AI_Assistant_Learnings","to":"meta_development_insights","relationType":"enriches"}
-{"type":"relation","from":"Effective_Response_Patterns","to":"AI_Assistant_Learnings","relationType":"implements"}
-{"type":"relation","from":"AI_Context_Management","to":"AI_Human_Collaboration_Model","relationType":"improves"}
-{"type":"relation","from":"AI_Tool_Usage_Patterns","to":"AI_Context_Management","relationType":"enables"}
-{"type":"relation","from":"AI_Assistant_Learnings","to":"Basic_Memory_Meta_Experience","relationType":"validates"}
-{"type":"relation","from":"AI_Tool_Usage_Patterns","to":"Model_Context_Protocol","relationType":"demonstrates_effective_use_of"}
-{"type":"relation","from":"AI_Context_Management","to":"basic-memory","relationType":"validates_design_of"}
-{"type":"relation","from":"Effective_Response_Patterns","to":"AI_Human_Development_Methodology","relationType":"refines"}
-{"type":"relation","to":"relation_service","from":"relation_service_patterns","relationType":"guides"}
-{"type":"relation","to":"test_driven_development","from":"test_driven_insights_relations","relationType":"enriches"}
-{"type":"relation","to":"implementation_challenges","from":"relation_service_learnings","relationType":"solves"}
-{"type":"relation","to":"basic-memory_implementation_patterns","from":"relation_service_patterns","relationType":"implements"}
-{"type":"relation","to":"markdown_format","from":"relation_service_patterns","relationType":"extends"}
-{"type":"relation","to":"service_layer_patterns","from":"relation_service_patterns","relationType":"refines"}
-{"type":"relation","from":"packaging_learnings","to":"implementation_challenges","relationType":"informs"}
-{"type":"relation","from":"packaging_learnings","to":"test_driven_development","relationType":"impacts"}
-{"type":"relation","to":"basic-memory","from":"Recent_Implementation_Progress","relationType":"updates_status_of"}
-{"type":"relation","to":"future_work","from":"Next_Steps","relationType":"extends"}
-{"type":"relation","to":"design_decisions","from":"Development_Practices","relationType":"informs"}
-{"type":"relation","to":"packaging_learnings","from":"Development_Practices","relationType":"incorporates"}
-{"type":"relation","to":"test_driven_development","from":"Development_Practices","relationType":"refines"}
-{"type":"relation","to":"basic-memory_implementation_patterns","from":"Development_Practices","relationType":"enhances"}
-{"type":"relation","from":"Basic_Memory_MCP","to":"MCP_Server_Implementation","relationType":"follows"}
-{"type":"relation","from":"Basic_Memory_MCP","to":"MCP_Tools","relationType":"uses"}
-{"type":"relation","from":"Basic_Memory","to":"MCP_Server_Implementation","relationType":"implements"}
-{"type":"relation","from":"Basic_Memory_Testing","to":"Memory_Service_Tests","relationType":"includes"}
-{"type":"relation","from":"Basic_Memory_Testing","to":"MCP_Server_Tests","relationType":"includes"}
-{"type":"relation","from":"Memory_Service_Tests","to":"Basic_Memory_MCP","relationType":"validates"}
-{"type":"relation","from":"MCP_Server_Tests","to":"Basic_Memory_MCP","relationType":"validates"}
-{"type":"relation","from":"Service_Interface_Audit","to":"Memory_Service_Refactoring","relationType":"informs"}
-{"type":"relation","from":"Memory_Service_Refactoring","to":"Basic_Memory_MCP","relationType":"affects"}
-{"type":"relation","from":"Memory_Service_Patterns","to":"Basic_Memory_MCP","relationType":"improves"}
-{"type":"relation","from":"Pydantic_Create_Pattern","to":"Memory_Service_Patterns","relationType":"enables"}
-{"type":"relation","from":"Pydantic_Create_Pattern","to":"Basic_Memory_MCP","relationType":"improves"}
-{"type":"relation","from":"MCP_Marketplace","to":"Basic_Memory_Business","relationType":"enables"}
-{"type":"relation","from":"Basic_Memory","to":"MCP_Marketplace","relationType":"could_integrate_with"}
-{"type":"relation","from":"Persistence_Of_Vision","to":"Basic_Memory","relationType":"helps_achieve"}
-{"type":"relation","from":"Drew","to":"Persistence_Of_Vision","relationType":"conceptualized"}
-{"type":"relation","to":"Usage_Recipes","from":"Conversation_Continuity_Pattern","relationType":"is_example_of"}
-{"type":"relation","to":"Basic_Memory","from":"Usage_Recipes","relationType":"enhances"}
-{"type":"relation","to":"Basic_Memory","from":"Chat_References","relationType":"enhances"}
-{"type":"relation","to":"Conversation_Continuity_Pattern","from":"Chat_References","relationType":"implements"}
-{"type":"relation","from":"20240307-chat-reference-protocol-test","to":"20240307-chat-reference-protocol","relationType":"continues_from"}
-{"type":"relation","from_id":"Run_Tests_Tool_Request","to_id":"Basic_Machines","relationType":"enhances","context":"development workflow improvement"}
-{"type":"relation","from_id":"SQLAlchemy_Async_Loading_Pattern","to_id":"basic-memory","relation_type":"improves","context":"database performance and async compatibility"}
-{"type":"relation","from_id":"SQLAlchemy_Async_Loading_Pattern","to_id":"Entity","relation_type":"applies_to","context":"relationship loading strategy"}
-{"type":"relation","from":"MCP_Reference_Integration","to":"Project_Priorities","relationType":"prioritized_after"}
-{"type":"relation","from":"great_observation_loading_saga_20241207","to":"Basic_Memory","relationType":"occurred_in"}
-{"type":"relation","from":"great_observation_loading_saga_20241207","to":"SQLAlchemy","relationType":"relates_to"}
-{"type":"relation","from":"basic_memory_implementation_20241208","to":"Basic_Memory","relationType":"improves"}
-{"type":"relation","from":"great_observation_loading_saga_20241207","to":"basic_memory_implementation_20241208","relationType":"leads_to"}
-{"type":"relation","from":"MCP_Dependency_Risk","to":"DIY_Ethics","relationType":"validates"}
-{"type":"relation","from":"MCP_Dependency_Risk","to":"basic-memory_core_principles","relationType":"reinforces"}
-{"type":"relation","from":"MCP_Dependency_Risk","to":"Basic_Memory_Implementation_Plan","relationType":"influences"}
-{"type":"relation","from":"basic_memory_mcp_architecture","to":"basic_memory_project_20241208","relationType":"implements"}
-{"type":"relation","from":"basic_memory_sync_considerations","to":"basic_memory_project_20241208","relationType":"influences"}
-{"type":"relation","from":"mcp_server_learnings","to":"basic_memory_mcp_architecture","relationType":"informs"}
-{"type":"relation","from":"20241208-mcp-tool-refactoring","to":"Basic_Memory_MCP","relationType":"improves"}
-{"type":"relation","from":"20241208-mcp-tool-refactoring","to":"Basic_Memory_Implementation_Plan","relationType":"implements"}

pyproject.toml

@@ -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.1"
+requires-python = ">=3.12"
 license = { text = "AGPL-3.0-or-later" }
 authors = [
     { name = "Basic Machines", email = "hello@basic-machines.co" }
@@ -14,9 +14,8 @@ dependencies = [
     "typer>=0.9.0",
     "aiosqlite>=0.20.0",
     "greenlet>=3.1.1",
-    "pydantic[email,timezone]>=2.10.3",
-    "icecream>=2.1.3",
-    "mcp>=1.2.0",
+    "pydantic[email,timezone]>=2.12.0",
+    "mcp>=1.23.1",
     "pydantic-settings>=2.6.1",
     "loguru>=0.7.3",
     "pyright>=1.1.390",
@@ -30,10 +29,21 @@ dependencies = [
     "alembic>=1.14.1",
     "pillow>=11.1.0",
     "pybars3>=0.9.7",
-    "fastmcp>=2.3.4",
+    "fastmcp==2.12.3", # Pinned - 2.14.x breaks MCP tools visibility (issue #463)
     "pyjwt>=2.10.1",
     "python-dotenv>=1.1.0",
     "pytest-aio>=1.9.0",
+    "aiofiles>=24.1.0", # Optional observability (disabled by default via config)
+    "asyncpg>=0.30.0",
+    "nest-asyncio>=1.6.0", # For Alembic migrations with Postgres
+    "pytest-asyncio>=1.2.0",
+    "psycopg==3.3.1",
+    "mdformat>=0.7.22",
+    "mdformat-gfm>=0.3.7",
+    "mdformat-frontmatter>=2.0.8",
+    "sniffio>=1.3.1",
+    "anyio>=4.10.0",
+    "httpx>=0.28.0",
 ]
 
 
@@ -52,17 +62,23 @@ build-backend = "hatchling.build"
 
 [tool.pytest.ini_options]
 pythonpath = ["src", "tests"]
-addopts = "--cov=basic_memory --cov-report term-missing -ra -q"
-testpaths = ["tests"]
+addopts = "--cov=basic_memory --cov-report term-missing"
+testpaths = ["tests", "test-int"]
 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"
 
-[tool.uv]
-dev-dependencies = [
+[dependency-groups]
+dev = [
     "gevent>=24.11.1",
     "icecream>=2.1.3",
     "pytest>=8.3.4",
@@ -71,6 +87,10 @@ dev-dependencies = [
     "pytest-asyncio>=0.24.0",
     "pytest-xdist>=3.0.0",
     "ruff>=0.1.6",
+    "freezegun>=1.5.5",
+    "testcontainers[postgres]>=4.0.0",
+    "psycopg>=3.2.0",
+    "pyright>=1.1.408",
 ]
 
 [tool.hatch.version]
@@ -95,6 +115,8 @@ pythonVersion = "3.12"
 
 [tool.coverage.run]
 concurrency = ["thread", "gevent"]
+parallel = true
+source = ["basic_memory"]
 
 [tool.coverage.report]
 exclude_lines = [
@@ -116,11 +138,9 @@ omit = [
     "*/supabase_auth_provider.py",  # External HTTP calls to Supabase APIs
     "*/watch_service.py",           # File system watching - complex integration testing
     "*/background_sync.py",         # Background processes
-    "*/cli/main.py",               # CLI entry point
-    "*/mcp/tools/project_management.py",  # Covered by integration tests
-    "*/mcp/tools/sync_status.py",  # Covered by integration tests
+    "*/cli/**",                    # CLI is an interactive wrapper; core logic is covered via API/MCP/service tests
+    "*/db.py",                     # Backend/runtime-dependent (sqlite/postgres/windows tuning); validated via integration tests
+    "*/services/initialization.py", # Startup orchestration + background tasks (watchers); exercised indirectly in entrypoints
+    "*/sync/sync_service.py",      # Heavy filesystem/db integration; covered by integration suite, not enforced in unit coverage
     "*/services/migration_service.py", # Complex migration scenarios
 ]
-
-[tool.logfire]
-ignore_no_config = true

server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.basicmachines-co/basic-memory",
+  "description": "Local-first knowledge management with bi-directional LLM sync via Markdown files.",
+  "repository": {
+    "url": "https://github.com/basicmachines-co/basic-memory.git",
+    "source": "github"
+  },
+  "version": "0.17.7",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "basic-memory",
+      "version": "0.17.7",
+      "runtimeHint": "uvx",
+      "runtimeArguments": ["basic-memory", "mcp"],
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

src/basic_memory/__init__.py

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

src/basic_memory/alembic/env.py

@@ -1,29 +1,60 @@
 """Alembic environment configuration."""
 
+import asyncio
 import os
 from logging.config import fileConfig
 
-from sqlalchemy import engine_from_config
-from sqlalchemy import pool
+# Allow nested event loops (needed for pytest-asyncio and other async contexts)
+# Note: nest_asyncio doesn't work with uvloop or Python 3.14+, so we handle those cases separately
+import sys
+
+if sys.version_info < (3, 14):
+    try:
+        import nest_asyncio
+
+        nest_asyncio.apply()
+    except (ImportError, ValueError):
+        # nest_asyncio not available or can't patch this loop type (e.g., uvloop)
+        pass
+# For Python 3.14+, we rely on the thread-based fallback in run_migrations_online()
+
+from sqlalchemy import engine_from_config, pool
+from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 
 from alembic import context
 
-# set config.env to "test" for pytest to prevent logging to file in utils.setup_logging()
-os.environ["BASIC_MEMORY_ENV"] = "test"
+from basic_memory.config import ConfigManager
+
+# Trigger: only set test env when actually running under pytest
+# Why: alembic/env.py is imported during normal operations (MCP server startup, migrations)
+#      but we only want test behavior during actual test runs
+# Outcome: prevents is_test_env from returning True in production, enabling watch service
+if os.getenv("PYTEST_CURRENT_TEST") is not None:
+    os.environ["BASIC_MEMORY_ENV"] = "test"
 
 # Import after setting environment variable  # noqa: E402
-from basic_memory.config import app_config  # noqa: E402
 from basic_memory.models import Base  # noqa: E402
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
 config = context.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)
+# 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
 
-# print(f"Using 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
+    )
+    config.set_main_option("sqlalchemy.url", sqlalchemy_url)
 
 # Interpret the config file for Python logging.
 if config.config_file_name is not None:
@@ -67,28 +98,89 @@ def run_migrations_offline() -> None:
         context.run_migrations()
 
 
+def do_run_migrations(connection):
+    """Execute migrations with the given connection."""
+    context.configure(
+        connection=connection,
+        target_metadata=target_metadata,
+        include_object=include_object,
+        render_as_batch=True,
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations(connectable):
+    """Run migrations asynchronously with AsyncEngine."""
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+    await connectable.dispose()
+
+
 def run_migrations_online() -> None:
     """Run migrations in 'online' mode.
 
-    In this scenario we need to create an Engine
-    and associate a connection with the context.
+    Supports both sync engines (SQLite) and async engines (PostgreSQL with asyncpg).
     """
-    connectable = engine_from_config(
-        config.get_section(config.config_ini_section, {}),
-        prefix="sqlalchemy.",
-        poolclass=pool.NullPool,
-    )
+    # Check if a connection/engine was provided (e.g., from run_migrations)
+    connectable = context.config.attributes.get("connection", None)
 
-    with connectable.connect() as connection:
-        context.configure(
-            connection=connection,
-            target_metadata=target_metadata,
-            include_object=include_object,
-            render_as_batch=True,
-        )
+    if connectable is None:
+        # No connection provided, create engine from config
+        url = context.config.get_main_option("sqlalchemy.url")
 
-        with context.begin_transaction():
-            context.run_migrations()
+        # Check if it's an async URL (sqlite+aiosqlite or postgresql+asyncpg)
+        if url and ("+asyncpg" in url or "+aiosqlite" in url):
+            # Create async engine for asyncpg or aiosqlite
+            connectable = create_async_engine(
+                url,
+                poolclass=pool.NullPool,
+                future=True,
+            )
+        else:
+            # Create sync engine for regular sqlite or postgresql
+            connectable = engine_from_config(
+                context.config.get_section(context.config.config_ini_section, {}),
+                prefix="sqlalchemy.",
+                poolclass=pool.NullPool,
+            )
+
+    # Handle async engines (PostgreSQL with asyncpg)
+    if isinstance(connectable, AsyncEngine):
+        # Try to run async migrations
+        # nest_asyncio allows asyncio.run() from within event loops, but doesn't work with uvloop
+        try:
+            asyncio.run(run_async_migrations(connectable))
+        except RuntimeError as e:
+            if "cannot be called from a running event loop" in str(e):
+                # We're in a running event loop (likely uvloop) - need to use a different approach
+                # Create a new thread to run the async migrations
+                import concurrent.futures
+
+                def run_in_thread():
+                    """Run async migrations in a new event loop in a separate thread."""
+                    new_loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(new_loop)
+                    try:
+                        new_loop.run_until_complete(run_async_migrations(connectable))
+                    finally:
+                        new_loop.close()
+
+                with concurrent.futures.ThreadPoolExecutor() as executor:
+                    future = executor.submit(run_in_thread)
+                    future.result()  # Wait for completion and re-raise any exceptions
+            else:
+                raise
+    else:
+        # Handle sync engines (SQLite) or sync connections
+        if hasattr(connectable, "connect"):
+            # It's an engine, get a connection
+            with connectable.connect() as connection:
+                do_run_migrations(connection)
+        else:
+            # It's already a connection
+            do_run_migrations(connectable)
 
 
 if context.is_offline_mode():

src/basic_memory/alembic/versions/314f1ea54dc4_add_postgres_full_text_search_support_.py

@@ -0,0 +1,131 @@
+"""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")

src/basic_memory/alembic/versions/5fe1ab1ccebe_add_projects_table.py

@@ -21,6 +21,12 @@ 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),
@@ -55,7 +61,9 @@ 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"),
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL")
+            if is_sqlite
+            else None,
         )
         batch_op.drop_index("ix_entity_file_path")
         batch_op.create_index(batch_op.f("ix_entity_file_path"), ["file_path"], unique=False)
@@ -67,12 +75,16 @@ 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"),
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL")
+            if is_sqlite
+            else None,
         )
         batch_op.create_foreign_key("fk_entity_project_id", "project", ["project_id"], ["id"])
 
     # drop the search index table. it will be recreated
-    op.drop_table("search_index")
+    # Only drop for SQLite - Postgres uses regular table managed by ORM
+    if is_sqlite:
+        op.drop_table("search_index")
 
     # ### end Alembic commands ###
 

src/basic_memory/alembic/versions/647e7a75e2cd_project_constraint_fix.py

@@ -25,43 +25,51 @@ 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.
 
-    Since SQLite doesn't support dropping specific constraints easily, we'll
-    recreate the table without the problematic constraint.
+    SQLite: Recreate the table without the constraint (no ALTER TABLE support)
+    Postgres: Use ALTER TABLE to drop the constraint directly
     """
-    # 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"),
-    )
+    connection = op.get_bind()
+    is_sqlite = connection.dialect.name == "sqlite"
 
-    # Copy data from old table to new table
-    op.execute("INSERT INTO project_new SELECT * FROM project")
+    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"),
+        )
 
-    # Drop the old table
-    op.drop_table("project")
+        # Copy data from old table to new table
+        op.execute("INSERT INTO project_new SELECT * FROM project")
 
-    # Rename the new table
-    op.rename_table("project_new", "project")
+        # Drop the old table
+        op.drop_table("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)
+        # 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")
 
 
 def downgrade() -> None:

src/basic_memory/alembic/versions/6830751f5fb6_merge_multiple_heads.py

@@ -0,0 +1,24 @@
+"""Merge multiple heads
+
+Revision ID: 6830751f5fb6
+Revises: a2b3c4d5e6f7, g9a0b3c4d5e6
+Create Date: 2025-12-29 12:46:46.476268
+
+"""
+
+from typing import Sequence, Union
+
+
+# revision identifiers, used by Alembic.
+revision: str = "6830751f5fb6"
+down_revision: Union[str, Sequence[str], None] = ("a2b3c4d5e6f7", "g9a0b3c4d5e6")
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

src/basic_memory/alembic/versions/9d9c1cb7d8f5_add_mtime_and_size_columns_to_entity_.py

@@ -0,0 +1,49 @@
+"""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 ###

src/basic_memory/alembic/versions/a1b2c3d4e5f6_fix_project_foreign_keys.py

@@ -0,0 +1,49 @@
+"""fix project foreign keys
+
+Revision ID: a1b2c3d4e5f6
+Revises: 647e7a75e2cd
+Create Date: 2025-08-19 22:06:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "a1b2c3d4e5f6"
+down_revision: Union[str, None] = "647e7a75e2cd"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Re-establish foreign key constraints that were lost during project table recreation.
+
+    The migration 647e7a75e2cd recreated the project table but did not re-establish
+    the foreign key constraint from entity.project_id to project.id, causing
+    foreign key constraint failures when trying to delete projects with related entities.
+    """
+    # SQLite doesn't allow adding foreign key constraints to existing tables easily
+    # We need to be careful and handle the case where the constraint might already exist
+
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        # Try to drop existing foreign key constraint (may not exist)
+        try:
+            batch_op.drop_constraint("fk_entity_project_id", type_="foreignkey")
+        except Exception:
+            # Constraint may not exist, which is fine - we'll create it next
+            pass
+
+        # Add the foreign key constraint with CASCADE DELETE
+        # This ensures that when a project is deleted, all related entities are also deleted
+        batch_op.create_foreign_key(
+            "fk_entity_project_id", "project", ["project_id"], ["id"], ondelete="CASCADE"
+        )
+
+
+def downgrade() -> None:
+    """Remove the foreign key constraint."""
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        batch_op.drop_constraint("fk_entity_project_id", type_="foreignkey")

src/basic_memory/alembic/versions/a2b3c4d5e6f7_add_search_index_entity_cascade.py

@@ -0,0 +1,56 @@
+"""Add cascade delete FK from search_index to entity
+
+Revision ID: a2b3c4d5e6f7
+Revises: f8a9b2c3d4e5
+Create Date: 2025-12-02 07:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "a2b3c4d5e6f7"
+down_revision: Union[str, None] = "f8a9b2c3d4e5"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add FK with CASCADE delete from search_index.entity_id to entity.id.
+
+    This migration is Postgres-only because:
+    - SQLite uses FTS5 virtual tables which don't support foreign keys
+    - The FK enables automatic cleanup of search_index entries when entities are deleted
+    """
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    if dialect == "postgresql":
+        # First, clean up any orphaned search_index entries where entity no longer exists
+        op.execute("""
+            DELETE FROM search_index
+            WHERE entity_id IS NOT NULL
+            AND entity_id NOT IN (SELECT id FROM entity)
+        """)
+
+        # Add FK with CASCADE - nullable FK allows search_index entries without entity_id
+        op.create_foreign_key(
+            "fk_search_index_entity_id",
+            "search_index",
+            "entity",
+            ["entity_id"],
+            ["id"],
+            ondelete="CASCADE",
+        )
+
+
+def downgrade() -> None:
+    """Remove the FK constraint."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    if dialect == "postgresql":
+        op.drop_constraint("fk_search_index_entity_id", "search_index", type_="foreignkey")

src/basic_memory/alembic/versions/cc7172b46608_update_search_index_schema.py

@@ -21,6 +21,12 @@ 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")
 
@@ -59,6 +65,13 @@ 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")
 

src/basic_memory/alembic/versions/e7e1f4367280_add_scan_watermark_tracking_to_project.py

@@ -0,0 +1,37 @@
+"""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 ###

src/basic_memory/alembic/versions/f8a9b2c3d4e5_add_pg_trgm_for_fuzzy_link_resolution.py

@@ -0,0 +1,239 @@
+"""Add project_id to relation/observation and pg_trgm for fuzzy link resolution
+
+Revision ID: f8a9b2c3d4e5
+Revises: 314f1ea54dc4
+Create Date: 2025-12-01 12:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy import text
+
+
+def column_exists(connection, table: str, column: str) -> bool:
+    """Check if a column exists in a table (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text(
+                "SELECT 1 FROM information_schema.columns "
+                "WHERE table_name = :table AND column_name = :column"
+            ),
+            {"table": table, "column": column},
+        )
+        return result.fetchone() is not None
+    else:
+        # SQLite
+        result = connection.execute(text(f"PRAGMA table_info({table})"))
+        columns = [row[1] for row in result]
+        return column in columns
+
+
+def index_exists(connection, index_name: str) -> bool:
+    """Check if an index exists (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text("SELECT 1 FROM pg_indexes WHERE indexname = :index_name"),
+            {"index_name": index_name},
+        )
+        return result.fetchone() is not None
+    else:
+        # SQLite
+        result = connection.execute(
+            text("SELECT 1 FROM sqlite_master WHERE type='index' AND name = :index_name"),
+            {"index_name": index_name},
+        )
+        return result.fetchone() is not None
+
+
+# revision identifiers, used by Alembic.
+revision: str = "f8a9b2c3d4e5"
+down_revision: Union[str, None] = "314f1ea54dc4"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add project_id to relation and observation tables, plus pg_trgm indexes.
+
+    This migration:
+    1. Adds project_id column to relation and observation tables (denormalization)
+    2. Backfills project_id from the associated entity
+    3. Enables pg_trgm extension for trigram-based fuzzy matching (Postgres only)
+    4. Creates GIN indexes on entity title and permalink for fast similarity searches
+    5. Creates partial index on unresolved relations for efficient bulk resolution
+    """
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    # -------------------------------------------------------------------------
+    # Add project_id to relation table
+    # -------------------------------------------------------------------------
+
+    # Step 1: Add project_id column as nullable first (idempotent)
+    if not column_exists(connection, "relation", "project_id"):
+        op.add_column("relation", sa.Column("project_id", sa.Integer(), nullable=True))
+
+        # Step 2: Backfill project_id from entity.project_id via from_id
+        if dialect == "postgresql":
+            op.execute("""
+                UPDATE relation
+                SET project_id = entity.project_id
+                FROM entity
+                WHERE relation.from_id = entity.id
+            """)
+        else:
+            # SQLite syntax
+            op.execute("""
+                UPDATE relation
+                SET project_id = (
+                    SELECT entity.project_id
+                    FROM entity
+                    WHERE entity.id = relation.from_id
+                )
+            """)
+
+        # Step 3: Make project_id NOT NULL and add foreign key
+        if dialect == "postgresql":
+            op.alter_column("relation", "project_id", nullable=False)
+            op.create_foreign_key(
+                "fk_relation_project_id",
+                "relation",
+                "project",
+                ["project_id"],
+                ["id"],
+            )
+        else:
+            # SQLite requires batch operations for ALTER COLUMN
+            with op.batch_alter_table("relation") as batch_op:
+                batch_op.alter_column("project_id", nullable=False)
+                batch_op.create_foreign_key(
+                    "fk_relation_project_id",
+                    "project",
+                    ["project_id"],
+                    ["id"],
+                )
+
+    # Step 4: Create index on relation.project_id (idempotent)
+    if not index_exists(connection, "ix_relation_project_id"):
+        op.create_index("ix_relation_project_id", "relation", ["project_id"])
+
+    # -------------------------------------------------------------------------
+    # Add project_id to observation table
+    # -------------------------------------------------------------------------
+
+    # Step 1: Add project_id column as nullable first (idempotent)
+    if not column_exists(connection, "observation", "project_id"):
+        op.add_column("observation", sa.Column("project_id", sa.Integer(), nullable=True))
+
+        # Step 2: Backfill project_id from entity.project_id via entity_id
+        if dialect == "postgresql":
+            op.execute("""
+                UPDATE observation
+                SET project_id = entity.project_id
+                FROM entity
+                WHERE observation.entity_id = entity.id
+            """)
+        else:
+            # SQLite syntax
+            op.execute("""
+                UPDATE observation
+                SET project_id = (
+                    SELECT entity.project_id
+                    FROM entity
+                    WHERE entity.id = observation.entity_id
+                )
+            """)
+
+        # Step 3: Make project_id NOT NULL and add foreign key
+        if dialect == "postgresql":
+            op.alter_column("observation", "project_id", nullable=False)
+            op.create_foreign_key(
+                "fk_observation_project_id",
+                "observation",
+                "project",
+                ["project_id"],
+                ["id"],
+            )
+        else:
+            # SQLite requires batch operations for ALTER COLUMN
+            with op.batch_alter_table("observation") as batch_op:
+                batch_op.alter_column("project_id", nullable=False)
+                batch_op.create_foreign_key(
+                    "fk_observation_project_id",
+                    "project",
+                    ["project_id"],
+                    ["id"],
+                )
+
+    # Step 4: Create index on observation.project_id (idempotent)
+    if not index_exists(connection, "ix_observation_project_id"):
+        op.create_index("ix_observation_project_id", "observation", ["project_id"])
+
+    # Postgres-specific: pg_trgm and GIN indexes
+    if dialect == "postgresql":
+        # Enable pg_trgm extension for fuzzy string matching
+        op.execute("CREATE EXTENSION IF NOT EXISTS pg_trgm")
+
+        # Create trigram indexes on entity table for fuzzy matching
+        # GIN indexes with gin_trgm_ops support similarity searches
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_entity_title_trgm
+            ON entity USING gin (title gin_trgm_ops)
+        """)
+
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_entity_permalink_trgm
+            ON entity USING gin (permalink gin_trgm_ops)
+        """)
+
+        # Create partial index on unresolved relations for efficient bulk resolution
+        # This makes "WHERE to_id IS NULL AND project_id = X" queries very fast
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_relation_unresolved
+            ON relation (project_id, to_name)
+            WHERE to_id IS NULL
+        """)
+
+        # Create index on relation.to_name for join performance in bulk resolution
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_relation_to_name
+            ON relation (to_name)
+        """)
+
+
+def downgrade() -> None:
+    """Remove project_id from relation/observation and pg_trgm indexes."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    if dialect == "postgresql":
+        # Drop Postgres-specific indexes
+        op.execute("DROP INDEX IF EXISTS idx_relation_to_name")
+        op.execute("DROP INDEX IF EXISTS idx_relation_unresolved")
+        op.execute("DROP INDEX IF EXISTS idx_entity_permalink_trgm")
+        op.execute("DROP INDEX IF EXISTS idx_entity_title_trgm")
+        # Note: We don't drop the pg_trgm extension as other code may depend on it
+
+        # Drop project_id from observation
+        op.drop_index("ix_observation_project_id", table_name="observation")
+        op.drop_constraint("fk_observation_project_id", "observation", type_="foreignkey")
+        op.drop_column("observation", "project_id")
+
+        # Drop project_id from relation
+        op.drop_index("ix_relation_project_id", table_name="relation")
+        op.drop_constraint("fk_relation_project_id", "relation", type_="foreignkey")
+        op.drop_column("relation", "project_id")
+    else:
+        # SQLite requires batch operations
+        op.drop_index("ix_observation_project_id", table_name="observation")
+        with op.batch_alter_table("observation") as batch_op:
+            batch_op.drop_constraint("fk_observation_project_id", type_="foreignkey")
+            batch_op.drop_column("project_id")
+
+        op.drop_index("ix_relation_project_id", table_name="relation")
+        with op.batch_alter_table("relation") as batch_op:
+            batch_op.drop_constraint("fk_relation_project_id", type_="foreignkey")
+            batch_op.drop_column("project_id")

src/basic_memory/alembic/versions/g9a0b3c4d5e6_add_external_id_to_project_and_entity.py

@@ -0,0 +1,173 @@
+"""Add external_id UUID column to project and entity tables
+
+Revision ID: g9a0b3c4d5e6
+Revises: f8a9b2c3d4e5
+Create Date: 2025-12-29 10:00:00.000000
+
+"""
+
+import uuid
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy import text
+
+
+def column_exists(connection, table: str, column: str) -> bool:
+    """Check if a column exists in a table (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text(
+                "SELECT 1 FROM information_schema.columns "
+                "WHERE table_name = :table AND column_name = :column"
+            ),
+            {"table": table, "column": column},
+        )
+        return result.fetchone() is not None
+    else:
+        # SQLite
+        result = connection.execute(text(f"PRAGMA table_info({table})"))
+        columns = [row[1] for row in result]
+        return column in columns
+
+
+def index_exists(connection, index_name: str) -> bool:
+    """Check if an index exists (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text("SELECT 1 FROM pg_indexes WHERE indexname = :index_name"),
+            {"index_name": index_name},
+        )
+        return result.fetchone() is not None
+    else:
+        # SQLite
+        result = connection.execute(
+            text("SELECT 1 FROM sqlite_master WHERE type='index' AND name = :index_name"),
+            {"index_name": index_name},
+        )
+        return result.fetchone() is not None
+
+
+# revision identifiers, used by Alembic.
+revision: str = "g9a0b3c4d5e6"
+down_revision: Union[str, None] = "f8a9b2c3d4e5"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add external_id UUID column to project and entity tables.
+
+    This migration:
+    1. Adds external_id column to project table
+    2. Adds external_id column to entity table
+    3. Generates UUIDs for existing rows
+    4. Creates unique indexes on both columns
+    """
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    # -------------------------------------------------------------------------
+    # Add external_id to project table
+    # -------------------------------------------------------------------------
+
+    if not column_exists(connection, "project", "external_id"):
+        # Step 1: Add external_id column as nullable first
+        op.add_column("project", sa.Column("external_id", sa.String(), nullable=True))
+
+        # Step 2: Generate UUIDs for existing rows
+        if dialect == "postgresql":
+            # Postgres has gen_random_uuid() function
+            op.execute("""
+                UPDATE project
+                SET external_id = gen_random_uuid()::text
+                WHERE external_id IS NULL
+            """)
+        else:
+            # SQLite: need to generate UUIDs in Python
+            result = connection.execute(text("SELECT id FROM project WHERE external_id IS NULL"))
+            for row in result:
+                new_uuid = str(uuid.uuid4())
+                connection.execute(
+                    text("UPDATE project SET external_id = :uuid WHERE id = :id"),
+                    {"uuid": new_uuid, "id": row[0]},
+                )
+
+        # Step 3: Make external_id NOT NULL
+        if dialect == "postgresql":
+            op.alter_column("project", "external_id", nullable=False)
+        else:
+            # SQLite requires batch operations for ALTER COLUMN
+            with op.batch_alter_table("project") as batch_op:
+                batch_op.alter_column("external_id", nullable=False)
+
+    # Step 4: Create unique index on project.external_id (idempotent)
+    if not index_exists(connection, "ix_project_external_id"):
+        op.create_index("ix_project_external_id", "project", ["external_id"], unique=True)
+
+    # -------------------------------------------------------------------------
+    # Add external_id to entity table
+    # -------------------------------------------------------------------------
+
+    if not column_exists(connection, "entity", "external_id"):
+        # Step 1: Add external_id column as nullable first
+        op.add_column("entity", sa.Column("external_id", sa.String(), nullable=True))
+
+        # Step 2: Generate UUIDs for existing rows
+        if dialect == "postgresql":
+            # Postgres has gen_random_uuid() function
+            op.execute("""
+                UPDATE entity
+                SET external_id = gen_random_uuid()::text
+                WHERE external_id IS NULL
+            """)
+        else:
+            # SQLite: need to generate UUIDs in Python
+            result = connection.execute(text("SELECT id FROM entity WHERE external_id IS NULL"))
+            for row in result:
+                new_uuid = str(uuid.uuid4())
+                connection.execute(
+                    text("UPDATE entity SET external_id = :uuid WHERE id = :id"),
+                    {"uuid": new_uuid, "id": row[0]},
+                )
+
+        # Step 3: Make external_id NOT NULL
+        if dialect == "postgresql":
+            op.alter_column("entity", "external_id", nullable=False)
+        else:
+            # SQLite requires batch operations for ALTER COLUMN
+            with op.batch_alter_table("entity") as batch_op:
+                batch_op.alter_column("external_id", nullable=False)
+
+    # Step 4: Create unique index on entity.external_id (idempotent)
+    if not index_exists(connection, "ix_entity_external_id"):
+        op.create_index("ix_entity_external_id", "entity", ["external_id"], unique=True)
+
+
+def downgrade() -> None:
+    """Remove external_id columns from project and entity tables."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    # Drop from entity table
+    if index_exists(connection, "ix_entity_external_id"):
+        op.drop_index("ix_entity_external_id", table_name="entity")
+
+    if column_exists(connection, "entity", "external_id"):
+        if dialect == "postgresql":
+            op.drop_column("entity", "external_id")
+        else:
+            with op.batch_alter_table("entity") as batch_op:
+                batch_op.drop_column("external_id")
+
+    # Drop from project table
+    if index_exists(connection, "ix_project_external_id"):
+        op.drop_index("ix_project_external_id", table_name="project")
+
+    if column_exists(connection, "project", "external_id"):
+        if dialect == "postgresql":
+            op.drop_column("project", "external_id")
+        else:
+            with op.batch_alter_table("project") as batch_op:
+                batch_op.drop_column("external_id")

src/basic_memory/api/app.py

@@ -1,6 +1,5 @@
 """FastAPI application for basic-memory knowledge graph API."""
 
-import asyncio
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI, HTTPException
@@ -8,7 +7,7 @@ from fastapi.exception_handlers import http_exception_handler
 from loguru import logger
 
 from basic_memory import __version__ as version
-from basic_memory import db
+from basic_memory.api.container import ApiContainer, set_container
 from basic_memory.api.routers import (
     directory_router,
     importer_router,
@@ -20,33 +19,57 @@ from basic_memory.api.routers import (
     search,
     prompt_router,
 )
-from basic_memory.config import app_config
-from basic_memory.services.initialization import initialize_app, initialize_file_sync
+from basic_memory.api.v2.routers import (
+    knowledge_router as v2_knowledge,
+    project_router as v2_project,
+    memory_router as v2_memory,
+    search_router as v2_search,
+    resource_router as v2_resource,
+    directory_router as v2_directory,
+    prompt_router as v2_prompt,
+    importer_router as v2_importer,
+)
+from basic_memory.config import init_api_logging
+from basic_memory.services.initialization import initialize_app
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):  # pragma: no cover
-    """Lifecycle manager for the FastAPI app."""
-    # Initialize app and database
-    logger.info("Starting Basic Memory API")
-    await initialize_app(app_config)
+    """Lifecycle manager for the FastAPI app. Not called in stdio mcp mode"""
 
-    logger.info(f"Sync changes enabled: {app_config.sync_changes}")
-    if app_config.sync_changes:
-        # start file sync task in background
-        app.state.sync_task = asyncio.create_task(initialize_file_sync(app_config))
-    else:
-        logger.info("Sync changes disabled. Skipping file sync service.")
+    # Initialize logging for API (stdout in cloud mode, file otherwise)
+    init_api_logging()
 
-    # proceed with startup
+    # --- Composition Root ---
+    # Create container and read config (single point of config access)
+    container = ApiContainer.create()
+    set_container(container)
+    app.state.container = container
+
+    logger.info(f"Starting Basic Memory API (mode={container.mode.name})")
+
+    await initialize_app(container.config)
+
+    # Cache database connections in app state for performance
+    logger.info("Initializing database and caching connections...")
+    engine, session_maker = await container.init_database()
+    app.state.engine = engine
+    app.state.session_maker = session_maker
+    logger.info("Database connections cached in app state")
+
+    # Create and start sync coordinator (lifecycle centralized in coordinator)
+    sync_coordinator = container.create_sync_coordinator()
+    await sync_coordinator.start()
+    app.state.sync_coordinator = sync_coordinator
+
+    # Proceed with startup
     yield
 
+    # Shutdown - coordinator handles clean task cancellation
     logger.info("Shutting down Basic Memory API")
-    if app.state.sync_task:
-        logger.info("Stopping sync...")
-        app.state.sync_task.cancel()  # pyright: ignore
+    await sync_coordinator.stop()
 
-    await db.shutdown_db()
+    await container.shutdown_database()
 
 
 # Initialize FastAPI app
@@ -57,8 +80,17 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
+# Include v2 routers FIRST (more specific paths must match before /{project} catch-all)
+app.include_router(v2_knowledge, prefix="/v2/projects/{project_id}")
+app.include_router(v2_memory, prefix="/v2/projects/{project_id}")
+app.include_router(v2_search, prefix="/v2/projects/{project_id}")
+app.include_router(v2_resource, prefix="/v2/projects/{project_id}")
+app.include_router(v2_directory, prefix="/v2/projects/{project_id}")
+app.include_router(v2_prompt, prefix="/v2/projects/{project_id}")
+app.include_router(v2_importer, prefix="/v2/projects/{project_id}")
+app.include_router(v2_project, prefix="/v2")
 
-# Include routers
+# Include v1 routers (/{project} is a catch-all, must come after specific prefixes)
 app.include_router(knowledge.router, prefix="/{project}")
 app.include_router(memory.router, prefix="/{project}")
 app.include_router(resource.router, prefix="/{project}")
@@ -68,12 +100,10 @@ app.include_router(directory_router.router, prefix="/{project}")
 app.include_router(prompt_router.router, prefix="/{project}")
 app.include_router(importer_router.router, prefix="/{project}")
 
-# Project resource router works accross projects
+# Project resource router works across projects
 app.include_router(project.project_resource_router)
 app.include_router(management.router)
 
-# Auth routes are handled by FastMCP automatically when auth is enabled
-
 
 @app.exception_handler(Exception)
 async def exception_handler(request, exc):  # pragma: no cover

src/basic_memory/api/container.py

@@ -0,0 +1,133 @@
+"""API composition root for Basic Memory.
+
+This container owns reading ConfigManager and environment variables for the
+API entrypoint. Downstream modules receive config/dependencies explicitly
+rather than reading globals.
+
+Design principles:
+- Only this module reads ConfigManager directly
+- Runtime mode (cloud/local/test) is resolved here
+- Factories for services are provided, not singletons
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, AsyncSession
+
+from basic_memory import db
+from basic_memory.config import BasicMemoryConfig, ConfigManager
+from basic_memory.runtime import RuntimeMode, resolve_runtime_mode
+
+if TYPE_CHECKING:  # pragma: no cover
+    from basic_memory.sync import SyncCoordinator
+
+
+@dataclass
+class ApiContainer:
+    """Composition root for the API entrypoint.
+
+    Holds resolved configuration and runtime context.
+    Created once at app startup, then used to wire dependencies.
+    """
+
+    config: BasicMemoryConfig
+    mode: RuntimeMode
+
+    # --- Database ---
+    # Cached database connections (set during lifespan startup)
+    engine: AsyncEngine | None = None
+    session_maker: async_sessionmaker[AsyncSession] | None = None
+
+    @classmethod
+    def create(cls) -> "ApiContainer":  # pragma: no cover
+        """Create container by reading ConfigManager.
+
+        This is the single point where API reads global config.
+        """
+        config = ConfigManager().config
+        mode = resolve_runtime_mode(
+            cloud_mode_enabled=config.cloud_mode_enabled,
+            is_test_env=config.is_test_env,
+        )
+        return cls(config=config, mode=mode)
+
+    # --- Runtime Mode Properties ---
+
+    @property
+    def should_sync_files(self) -> bool:
+        """Whether file sync should be started.
+
+        Sync is enabled when:
+        - sync_changes is True in config
+        - Not in test mode (tests manage their own sync)
+        """
+        return self.config.sync_changes and not self.mode.is_test
+
+    @property
+    def sync_skip_reason(self) -> str | None:  # pragma: no cover
+        """Reason why sync is skipped, or None if sync should run.
+
+        Useful for logging why sync was disabled.
+        """
+        if self.mode.is_test:
+            return "Test environment detected"
+        if not self.config.sync_changes:
+            return "Sync changes disabled"
+        return None
+
+    def create_sync_coordinator(self) -> "SyncCoordinator":  # pragma: no cover
+        """Create a SyncCoordinator with this container's settings.
+
+        Returns:
+            SyncCoordinator configured for this runtime environment
+        """
+        # Deferred import to avoid circular dependency
+        from basic_memory.sync import SyncCoordinator
+
+        return SyncCoordinator(
+            config=self.config,
+            should_sync=self.should_sync_files,
+            skip_reason=self.sync_skip_reason,
+        )
+
+    # --- Database Factory ---
+
+    async def init_database(  # pragma: no cover
+        self,
+    ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
+        """Initialize and cache database connections.
+
+        Returns:
+            Tuple of (engine, session_maker)
+        """
+        engine, session_maker = await db.get_or_create_db(self.config.database_path)
+        self.engine = engine
+        self.session_maker = session_maker
+        return engine, session_maker
+
+    async def shutdown_database(self) -> None:  # pragma: no cover
+        """Clean up database connections."""
+        await db.shutdown_db()
+
+
+# Module-level container instance (set by lifespan)
+# This allows deps.py to access the container without reading ConfigManager
+_container: ApiContainer | None = None
+
+
+def get_container() -> ApiContainer:
+    """Get the current API container.
+
+    Raises:
+        RuntimeError: If container hasn't been initialized
+    """
+    if _container is None:
+        raise RuntimeError("API container not initialized. Call set_container() first.")
+    return _container
+
+
+def set_container(container: ApiContainer) -> None:
+    """Set the API container (called by lifespan)."""
+    global _container
+    _container = container

src/basic_memory/api/routers/directory_router.py

@@ -10,7 +10,7 @@ from basic_memory.schemas.directory import DirectoryNode
 router = APIRouter(prefix="/directory", tags=["directory"])
 
 
-@router.get("/tree", response_model=DirectoryNode)
+@router.get("/tree", response_model=DirectoryNode, response_model_exclude_none=True)
 async def get_directory_tree(
     directory_service: DirectoryServiceDep,
     project_id: ProjectIdDep,
@@ -31,7 +31,28 @@ async def get_directory_tree(
     return tree
 
 
-@router.get("/list", response_model=List[DirectoryNode])
+@router.get("/structure", response_model=DirectoryNode, response_model_exclude_none=True)
+async def get_directory_structure(
+    directory_service: DirectoryServiceDep,
+    project_id: ProjectIdDep,
+):
+    """Get folder structure for navigation (no files).
+
+    Optimized endpoint for folder tree navigation. Returns only directory nodes
+    without file metadata. For full tree with files, use /directory/tree.
+
+    Args:
+        directory_service: Service for directory operations
+        project_id: ID of the current project
+
+    Returns:
+        DirectoryNode tree containing only folders (type="directory")
+    """
+    structure = await directory_service.get_directory_structure()
+    return structure
+
+
+@router.get("/list", response_model=List[DirectoryNode], response_model_exclude_none=True)
 async def list_directory(
     directory_service: DirectoryServiceDep,
     project_id: ProjectIdDep,

src/basic_memory/api/routers/knowledge_router.py

@@ -1,4 +1,11 @@
-"""Router for knowledge graph operations."""
+"""Router for knowledge graph operations.
+
+⚠️ DEPRECATED: This v1 API is deprecated and will be removed on June 30, 2026.
+Please migrate to /v2/{project}/knowledge endpoints which use entity IDs instead
+of path-based identifiers for improved performance and stability.
+
+Migration guide: See docs/migration/v1-to-v2.md
+"""
 
 from typing import Annotated
 
@@ -25,7 +32,32 @@ from basic_memory.schemas import (
 from basic_memory.schemas.request import EditEntityRequest, MoveEntityRequest
 from basic_memory.schemas.base import Permalink, Entity
 
-router = APIRouter(prefix="/knowledge", tags=["knowledge"])
+router = APIRouter(
+    prefix="/knowledge",
+    tags=["knowledge"],
+    deprecated=True,  # Marks entire router as deprecated in OpenAPI docs
+)
+
+
+async def resolve_relations_background(sync_service, entity_id: int, entity_permalink: str) -> None:
+    """Background task to resolve relations for a specific entity.
+
+    This runs asynchronously after the API response is sent, preventing
+    long delays when creating entities with many relations.
+    """
+    try:
+        # Only resolve relations for the newly created entity
+        await sync_service.resolve_relations(entity_id=entity_id)
+        logger.debug(
+            f"Background: Resolved relations for entity {entity_permalink} (id={entity_id})"
+        )
+    except Exception as e:  # pragma: no cover
+        # Log but don't fail - this is a background task.
+        # Avoid forcing synthetic failures just for coverage.
+        logger.warning(  # pragma: no cover
+            f"Background: Failed to resolve relations for entity {entity_permalink}: {e}"
+        )
+
 
 ## Create endpoints
 
@@ -88,15 +120,12 @@ async def create_or_update_entity(
     # reindex
     await search_service.index_entity(entity, background_tasks=background_tasks)
 
-    # Attempt immediate relation resolution when creating new entities
-    # This helps resolve forward references when related entities are created in the same session
+    # Schedule relation resolution as a background task for new entities
+    # This prevents blocking the API response while resolving potentially many relations
     if created:
-        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}")
+        background_tasks.add_task(
+            resolve_relations_background, sync_service, entity.id, entity.permalink or ""
+        )
 
     result = EntityResponse.model_validate(entity)
 

src/basic_memory/api/routers/management_router.py

@@ -6,7 +6,7 @@ from fastapi import APIRouter, Request
 from loguru import logger
 from pydantic import BaseModel
 
-from basic_memory.config import app_config
+from basic_memory.config import ConfigManager
 from basic_memory.deps import SyncServiceDep, ProjectRepositoryDep
 
 router = APIRouter(prefix="/management", tags=["management"])
@@ -41,6 +41,8 @@ async def start_watch_service(
         # Watch service is already running
         return WatchStatusResponse(running=True)
 
+    app_config = ConfigManager().config
+
     # Create and start a new watch service
     logger.info("Starting watch service via management API")
 

src/basic_memory/api/routers/project_router.py

@@ -1,18 +1,27 @@
 """Router for project management."""
 
-from fastapi import APIRouter, HTTPException, Path, Body
+import os
+from fastapi import APIRouter, HTTPException, Path, Body, BackgroundTasks, Response, Query
 from typing import Optional
+from loguru import logger
 
-from basic_memory.deps import ProjectServiceDep, ProjectPathDep
-from basic_memory.schemas import ProjectInfoResponse
+from basic_memory.deps import (
+    ProjectConfigDep,
+    ProjectServiceDep,
+    ProjectPathDep,
+    SyncServiceDep,
+)
+from basic_memory.schemas import ProjectInfoResponse, SyncReportResponse
 from basic_memory.schemas.project_info import (
     ProjectList,
     ProjectItem,
     ProjectInfoRequest,
     ProjectStatusResponse,
 )
+from basic_memory.utils import normalize_project_path
 
 # Router for resources in a specific project
+# The ProjectPathDep is used in the path as a prefix, so the request path is like /{project}/project/info
 project_router = APIRouter(prefix="/project", tags=["project"])
 
 # Router for managing project resources
@@ -28,45 +37,159 @@ async def get_project_info(
     return await project_service.get_project_info(project)
 
 
+@project_router.get("/item", response_model=ProjectItem)
+async def get_project(
+    project_service: ProjectServiceDep,
+    project: ProjectPathDep,
+) -> ProjectItem:
+    """Get bassic info about the specified Basic Memory project."""
+    found_project = await project_service.get_project(project)
+    if not found_project:
+        raise HTTPException(
+            status_code=404, detail=f"Project: '{project}' does not exist"
+        )  # pragma: no cover
+
+    return ProjectItem(
+        id=found_project.id,
+        external_id=found_project.external_id,
+        name=found_project.name,
+        path=normalize_project_path(found_project.path),
+        is_default=found_project.is_default or False,
+    )
+
+
 # Update a project
 @project_router.patch("/{name}", response_model=ProjectStatusResponse)
 async def update_project(
     project_service: ProjectServiceDep,
-    project_name: str = Path(..., description="Name of the project to update"),
-    path: Optional[str] = Body(None, description="New path for the project"),
+    name: str = Path(..., description="Name of the project to update"),
+    path: Optional[str] = Body(None, description="New absolute path for the project"),
     is_active: Optional[bool] = Body(None, description="Status of the project (active/inactive)"),
 ) -> ProjectStatusResponse:
     """Update a project's information in configuration and database.
 
     Args:
-        project_name: The name of the project to update
-        path: Optional new path for the project
+        name: The name of the project to update
+        path: Optional new absolute path for the project
         is_active: Optional status update for the project
 
     Returns:
         Response confirming the project was updated
     """
-    try:  # pragma: no cover
+    try:
+        # Validate that path is absolute if provided
+        if path and not os.path.isabs(path):
+            raise HTTPException(status_code=400, detail="Path must be absolute")
+
         # Get original project info for the response
+        old_project = await project_service.get_project(name)
+        if not old_project:
+            raise HTTPException(
+                status_code=400, detail=f"Project '{name}' not found in configuration"
+            )
+
         old_project_info = ProjectItem(
-            name=project_name,
-            path=project_service.projects.get(project_name, ""),
+            id=old_project.id,
+            external_id=old_project.external_id,
+            name=old_project.name,
+            path=old_project.path,
+            is_default=old_project.is_default or False,
         )
 
-        await project_service.update_project(project_name, updated_path=path, is_active=is_active)
+        if path:
+            await project_service.move_project(name, path)
+        elif is_active is not None:
+            await project_service.update_project(name, is_active=is_active)
 
         # Get updated project info
-        updated_path = path if path else project_service.projects.get(project_name, "")
+        updated_project = await project_service.get_project(name)
+        if not updated_project:
+            raise HTTPException(  # pragma: no cover
+                status_code=404, detail=f"Project '{name}' not found after update"
+            )
 
         return ProjectStatusResponse(
-            message=f"Project '{project_name}' updated successfully",
+            message=f"Project '{name}' updated successfully",
             status="success",
-            default=(project_name == project_service.default_project),
+            default=(name == project_service.default_project),
             old_project=old_project_info,
-            new_project=ProjectItem(name=project_name, path=updated_path),
+            new_project=ProjectItem(
+                id=updated_project.id,
+                external_id=updated_project.external_id,
+                name=updated_project.name,
+                path=updated_project.path,
+                is_default=updated_project.is_default or False,
+            ),
         )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))  # pragma: no cover
+
+
+# Sync project filesystem
+@project_router.post("/sync")
+async def sync_project(
+    background_tasks: BackgroundTasks,
+    sync_service: SyncServiceDep,
+    project_config: ProjectConfigDep,
+    force_full: bool = Query(
+        False, description="Force full scan, bypassing watermark optimization"
+    ),
+    run_in_background: bool = Query(True, description="Run in background"),
+):
+    """Force project filesystem sync to database.
+
+    Scans the project directory and updates the database with any new or modified files.
+
+    Args:
+        background_tasks: FastAPI background tasks
+        sync_service: Sync service for this project
+        project_config: Project configuration
+        force_full: If True, force a full scan even if watermark exists
+        run_in_background: If True, run sync in background and return immediately
+
+    Returns:
+        Response confirming sync was initiated (background) or SyncReportResponse (foreground)
+    """
+    if run_in_background:
+        background_tasks.add_task(
+            sync_service.sync, project_config.home, project_config.name, force_full=force_full
+        )
+        logger.info(
+            f"Filesystem sync initiated for project: {project_config.name} (force_full={force_full})"
+        )
+
+        return {
+            "status": "sync_started",
+            "message": f"Filesystem sync initiated for project '{project_config.name}'",
+        }
+    else:
+        report = await sync_service.sync(
+            project_config.home, project_config.name, force_full=force_full
+        )
+        logger.info(
+            f"Filesystem sync completed for project: {project_config.name} (force_full={force_full})"
+        )
+        return SyncReportResponse.from_sync_report(report)
+
+
+@project_router.post("/status", response_model=SyncReportResponse)
+async def project_sync_status(
+    sync_service: SyncServiceDep,
+    project_config: ProjectConfigDep,
+) -> SyncReportResponse:
+    """Scan directory for changes compared to database state.
+
+    Args:
+        sync_service: Sync service for this project
+        project_config: Project configuration
+
+    Returns:
+        Scan report with details on files that need syncing
+    """
+    logger.info(f"Scanning filesystem for project: {project_config.name}")  # pragma: no cover
+    sync_report = await sync_service.scan(project_config.home)  # pragma: no cover
+
+    return SyncReportResponse.from_sync_report(sync_report)  # pragma: no cover
 
 
 # List all available projects
@@ -84,8 +207,10 @@ async def list_projects(
 
     project_items = [
         ProjectItem(
+            id=project.id,
+            external_id=project.external_id,
             name=project.name,
-            path=project.path,
+            path=normalize_project_path(project.path),
             is_default=project.is_default or False,
         )
         for project in projects
@@ -98,8 +223,9 @@ async def list_projects(
 
 
 # Add a new project
-@project_resource_router.post("/projects", response_model=ProjectStatusResponse)
+@project_resource_router.post("/projects", response_model=ProjectStatusResponse, status_code=201)
 async def add_project(
+    response: Response,
     project_data: ProjectInfoRequest,
     project_service: ProjectServiceDep,
 ) -> ProjectStatusResponse:
@@ -111,17 +237,59 @@ 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(
+                    id=existing_project.id,
+                    external_id=existing_project.external_id,
+                    name=existing_project.name,
+                    path=existing_project.path,
+                    is_default=existing_project.is_default or False,
+                ),
+            )
+        else:
+            # Same name, different path - this is an error
+            raise HTTPException(
+                status_code=400,
+                detail=f"Project '{project_data.name}' already exists with different path. Existing: {existing_project.path}, Requested: {project_data.path}",
+            )
+
     try:  # pragma: no cover
+        # The service layer now handles cloud mode validation and path sanitization
         await project_service.add_project(
             project_data.name, project_data.path, set_default=project_data.set_default
         )
 
+        # Fetch the newly created project to get its ID
+        new_project = await project_service.get_project(project_data.name)
+        if not new_project:
+            raise HTTPException(status_code=500, detail="Failed to retrieve newly created project")
+
         return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
-            message=f"Project '{project_data.name}' added successfully",
+            message=f"Project '{new_project.name}' added successfully",
             status="success",
             default=project_data.set_default,
             new_project=ProjectItem(
-                name=project_data.name, path=project_data.path, is_default=project_data.set_default
+                id=new_project.id,
+                external_id=new_project.external_id,
+                name=new_project.name,
+                path=new_project.path,
+                is_default=new_project.is_default or False,
             ),
         )
     except ValueError as e:  # pragma: no cover
@@ -133,11 +301,15 @@ 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
@@ -149,13 +321,32 @@ async def remove_project(
                 status_code=404, detail=f"Project: '{name}' does not exist"
             )  # pragma: no cover
 
-        await project_service.remove_project(name)
+        # 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)
 
         return ProjectStatusResponse(
-            message=f"Project '{name}' removed successfully",
+            message=f"Project '{old_project.name}' removed successfully",
             status="success",
             default=False,
-            old_project=ProjectItem(name=old_project.name, path=old_project.path),
+            old_project=ProjectItem(
+                id=old_project.id,
+                external_id=old_project.external_id,
+                name=old_project.name,
+                path=old_project.path,
+                is_default=old_project.is_default or False,
+            ),
             new_project=None,
         )
     except ValueError as e:  # pragma: no cover
@@ -198,8 +389,16 @@ async def set_default_project(
             message=f"Project '{name}' set as default successfully",
             status="success",
             default=True,
-            old_project=ProjectItem(name=default_name, path=default_project.path),
+            old_project=ProjectItem(
+                id=default_project.id,
+                external_id=default_project.external_id,
+                name=default_name,
+                path=default_project.path,
+                is_default=False,
+            ),
             new_project=ProjectItem(
+                id=new_default_project.id,
+                external_id=new_default_project.external_id,
                 name=name,
                 path=new_default_project.path,
                 is_default=True,
@@ -209,8 +408,35 @@ async def set_default_project(
         raise HTTPException(status_code=400, detail=str(e))
 
 
+# Get the default project
+@project_resource_router.get("/default", response_model=ProjectItem)
+async def get_default_project(
+    project_service: ProjectServiceDep,
+) -> ProjectItem:
+    """Get the default project.
+
+    Returns:
+        Response with project default information
+    """
+    # Get the old default project
+    default_name = project_service.default_project
+    default_project = await project_service.get_project(default_name)
+    if not default_project:  # pragma: no cover
+        raise HTTPException(  # pragma: no cover
+            status_code=404, detail=f"Default Project: '{default_name}' does not exist"
+        )
+
+    return ProjectItem(
+        id=default_project.id,
+        external_id=default_project.external_id,
+        name=default_project.name,
+        path=default_project.path,
+        is_default=True,
+    )
+
+
 # Synchronize projects between config and database
-@project_resource_router.post("/sync", response_model=ProjectStatusResponse)
+@project_resource_router.post("/config/sync", response_model=ProjectStatusResponse)
 async def synchronize_projects(
     project_service: ProjectServiceDep,
 ) -> ProjectStatusResponse:

src/basic_memory/api/routers/resource_router.py

@@ -1,10 +1,11 @@
 """Routes for getting entity content."""
 
 import tempfile
+import uuid
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Union
 
-from fastapi import APIRouter, HTTPException, BackgroundTasks, Body
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Body, Response
 from fastapi.responses import FileResponse, JSONResponse
 from loguru import logger
 
@@ -25,6 +26,17 @@ from datetime import datetime
 router = APIRouter(prefix="/resource", tags=["resources"])
 
 
+def _mtime_to_datetime(entity: EntityModel) -> datetime:
+    """Convert entity mtime (file modification time) to datetime.
+
+    Returns the file's actual modification time, falling back to updated_at
+    if mtime is not available.
+    """
+    if entity.mtime:  # pragma: no cover
+        return datetime.fromtimestamp(entity.mtime).astimezone()  # pragma: no cover
+    return entity.updated_at
+
+
 def get_entity_ids(item: SearchIndexRow) -> set[int]:
     match item.type:
         case SearchItemType.ENTITY:
@@ -39,7 +51,7 @@ def get_entity_ids(item: SearchIndexRow) -> set[int]:
             raise ValueError(f"Unexpected type: {item.type}")
 
 
-@router.get("/{identifier:path}")
+@router.get("/{identifier:path}", response_model=None)
 async def get_resource_content(
     config: ProjectConfigDep,
     link_resolver: LinkResolverDep,
@@ -50,7 +62,7 @@ async def get_resource_content(
     identifier: str,
     page: int = 1,
     page_size: int = 10,
-) -> FileResponse:
+) -> Union[Response, FileResponse]:
     """Get resource content by identifier: name or permalink."""
     logger.debug(f"Getting content for: {identifier}")
 
@@ -81,13 +93,16 @@ async def get_resource_content(
     # return single response
     if len(results) == 1:
         entity = results[0]
-        file_path = Path(f"{config.home}/{entity.file_path}")
-        if not file_path.exists():
+        # Check file exists via file_service (for cloud compatibility)
+        if not await file_service.exists(entity.file_path):
             raise HTTPException(
                 status_code=404,
-                detail=f"File not found: {file_path}",
+                detail=f"File not found: {entity.file_path}",
             )
-        return FileResponse(path=file_path)
+        # Read content via file_service as bytes (works with both local and S3)
+        content = await file_service.read_file_bytes(entity.file_path)
+        content_type = file_service.content_type(entity.file_path)
+        return Response(content=content, media_type=content_type)
 
     # for multiple files, initialize a temporary file for writing the results
     with tempfile.NamedTemporaryFile(delete=False, mode="w", suffix=".md") as tmp_file:
@@ -97,7 +112,7 @@ async def get_resource_content(
             # Read content for each entity
             content = await file_service.read_entity_content(result)
             memory_url = normalize_memory_url(result.permalink)
-            modified_date = result.updated_at.isoformat()
+            modified_date = _mtime_to_datetime(result).isoformat()
             checksum = result.checksum[:8] if result.checksum else ""
 
             # Prepare the delimited content
@@ -151,27 +166,37 @@ 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(  # pragma: no cover
+                f"Error writing resource {file_path}: "
+                f"content is a dict, expected string. Keys: {list(content.keys())}"
+            )
+            raise HTTPException(  # pragma: no cover
+                status_code=400,
+                detail="content must be a string, not a dict. "
+                "Ensure request body is sent as raw string content, not JSON object.",
+            )
+
         # Ensure it's UTF-8 string content
         if isinstance(content, bytes):  # pragma: no cover
             content_str = content.decode("utf-8")
         else:
             content_str = str(content)
 
-        # Get full file path
-        full_path = Path(f"{config.home}/{file_path}")
-
-        # Ensure parent directory exists
-        full_path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Write content to file
-        checksum = await file_service.write_file(full_path, content_str)
+        # Cloud compatibility: do not assume a local filesystem path structure.
+        # Delegate directory creation + writes to the configured FileService (local or S3).
+        await file_service.ensure_directory(Path(file_path).parent)
+        checksum = await file_service.write_file(file_path, content_str)
 
         # Get file info
-        file_stats = file_service.file_stats(full_path)
+        file_metadata = await file_service.get_file_metadata(file_path)
 
         # Determine file details
         file_name = Path(file_path).name
-        content_type = file_service.content_type(full_path)
+        content_type = file_service.content_type(file_path)
 
         entity_type = "canvas" if file_path.endswith(".canvas") else "file"
 
@@ -188,20 +213,22 @@ async def write_resource(
                     "content_type": content_type,
                     "file_path": file_path,
                     "checksum": checksum,
-                    "updated_at": datetime.fromtimestamp(file_stats.st_mtime),
+                    "updated_at": file_metadata.modified_at,
                 },
             )
             status_code = 200
         else:
             # Create a new entity model
+            # Explicitly set external_id to ensure NOT NULL constraint is satisfied (fixes #512)
             entity = EntityModel(
+                external_id=str(uuid.uuid4()),
                 title=file_name,
                 entity_type=entity_type,
                 content_type=content_type,
                 file_path=file_path,
                 checksum=checksum,
-                created_at=datetime.fromtimestamp(file_stats.st_ctime),
-                updated_at=datetime.fromtimestamp(file_stats.st_mtime),
+                created_at=file_metadata.created_at,
+                updated_at=file_metadata.modified_at,
             )
             entity = await entity_repository.add(entity)
             status_code = 201
@@ -215,9 +242,9 @@ async def write_resource(
             content={
                 "file_path": file_path,
                 "checksum": checksum,
-                "size": file_stats.st_size,
-                "created_at": file_stats.st_ctime,
-                "modified_at": file_stats.st_mtime,
+                "size": file_metadata.size,
+                "created_at": file_metadata.created_at.timestamp(),
+                "modified_at": file_metadata.modified_at.timestamp(),
             },
         )
     except Exception as e:  # pragma: no cover

src/basic_memory/api/routers/utils.py

@@ -24,11 +24,30 @@ async def to_graph_context(
     page: Optional[int] = None,
     page_size: Optional[int] = None,
 ):
+    # First pass: collect all entity IDs needed for relations
+    entity_ids_needed: set[int] = set()
+    for context_item in context_result.results:
+        for item in (
+            [context_item.primary_result] + context_item.observations + context_item.related_results
+        ):
+            if item.type == SearchItemType.RELATION:
+                if item.from_id:  # pyright: ignore
+                    entity_ids_needed.add(item.from_id)  # pyright: ignore
+                if item.to_id:
+                    entity_ids_needed.add(item.to_id)
+
+    # Batch fetch all entities at once
+    entity_lookup: dict[int, str] = {}
+    if entity_ids_needed:
+        entities = await entity_repository.find_by_ids(list(entity_ids_needed))
+        entity_lookup = {e.id: e.title for e in entities}
+
     # Helper function to convert items to summaries
-    async def to_summary(item: SearchIndexRow | ContextResultRow):
+    def to_summary(item: SearchIndexRow | ContextResultRow):
         match item.type:
             case SearchItemType.ENTITY:
                 return EntitySummary(
+                    entity_id=item.id,
                     title=item.title,  # pyright: ignore
                     permalink=item.permalink,
                     content=item.content,
@@ -37,6 +56,8 @@ async def to_graph_context(
                 )
             case SearchItemType.OBSERVATION:
                 return ObservationSummary(
+                    observation_id=item.id,
+                    entity_id=item.entity_id,  # pyright: ignore
                     title=item.title,  # pyright: ignore
                     file_path=item.file_path,
                     category=item.category,  # pyright: ignore
@@ -45,15 +66,19 @@ async def to_graph_context(
                     created_at=item.created_at,
                 )
             case SearchItemType.RELATION:
-                from_entity = await entity_repository.find_by_id(item.from_id)  # pyright: ignore
-                to_entity = await entity_repository.find_by_id(item.to_id) if item.to_id else None
+                from_title = entity_lookup.get(item.from_id) if item.from_id else None  # pyright: ignore
+                to_title = entity_lookup.get(item.to_id) if item.to_id else None
                 return RelationSummary(
+                    relation_id=item.id,
+                    entity_id=item.entity_id,  # pyright: ignore
                     title=item.title,  # pyright: ignore
                     file_path=item.file_path,
                     permalink=item.permalink,  # pyright: ignore
                     relation_type=item.relation_type,  # pyright: ignore
-                    from_entity=from_entity.title if from_entity else None,
-                    to_entity=to_entity.title if to_entity else None,
+                    from_entity=from_title,
+                    from_entity_id=item.from_id,  # pyright: ignore
+                    to_entity=to_title,
+                    to_entity_id=item.to_id,
                     created_at=item.created_at,
                 )
             case _:  # pragma: no cover
@@ -63,23 +88,19 @@ async def to_graph_context(
     hierarchical_results = []
     for context_item in context_result.results:
         # Process primary result
-        primary_result = await to_summary(context_item.primary_result)
+        primary_result = to_summary(context_item.primary_result)
 
-        # Process observations
-        observations = []
-        for obs in context_item.observations:
-            observations.append(await to_summary(obs))
+        # Process observations (always ObservationSummary, validated by context_service)
+        observations = [to_summary(obs) for obs in context_item.observations]
 
         # Process related results
-        related = []
-        for rel in context_item.related_results:
-            related.append(await to_summary(rel))
+        related = [to_summary(rel) for rel in context_item.related_results]
 
         # Add to hierarchical results
         hierarchical_results.append(
             ContextResult(
                 primary_result=primary_result,
-                observations=observations,
+                observations=observations,  # pyright: ignore[reportArgumentType]
                 related_results=related,
             )
         )
@@ -111,6 +132,21 @@ async def to_search_results(entity_service: EntityService, results: List[SearchI
     search_results = []
     for r in results:
         entities = await entity_service.get_entities_by_id([r.entity_id, r.from_id, r.to_id])  # pyright: ignore
+
+        # Determine which IDs to set based on type
+        entity_id = None
+        observation_id = None
+        relation_id = None
+
+        if r.type == SearchItemType.ENTITY:
+            entity_id = r.id
+        elif r.type == SearchItemType.OBSERVATION:
+            observation_id = r.id
+            entity_id = r.entity_id  # Parent entity
+        elif r.type == SearchItemType.RELATION:
+            relation_id = r.id
+            entity_id = r.entity_id  # Parent entity
+
         search_results.append(
             SearchResult(
                 title=r.title,  # pyright: ignore
@@ -121,6 +157,9 @@ async def to_search_results(entity_service: EntityService, results: List[SearchI
                 content=r.content,
                 file_path=r.file_path,
                 metadata=r.metadata,
+                entity_id=entity_id,
+                observation_id=observation_id,
+                relation_id=relation_id,
                 category=r.category,
                 from_entity=entities[0].permalink if entities else None,
                 to_entity=entities[1].permalink if len(entities) > 1 else None,

src/basic_memory/api/v2/__init__.py

@@ -0,0 +1,35 @@
+"""API v2 module - ID-based entity references.
+
+Version 2 of the Basic Memory API uses integer entity IDs as the primary
+identifier for improved performance and stability.
+
+Key changes from v1:
+- Entity lookups use integer IDs instead of paths/permalinks
+- Direct database queries instead of cascading resolution
+- Stable references that don't change with file moves
+- Better caching support
+
+All v2 routers are registered with the /v2 prefix.
+"""
+
+from basic_memory.api.v2.routers import (
+    knowledge_router,
+    memory_router,
+    project_router,
+    resource_router,
+    search_router,
+    directory_router,
+    prompt_router,
+    importer_router,
+)
+
+__all__ = [
+    "knowledge_router",
+    "memory_router",
+    "project_router",
+    "resource_router",
+    "search_router",
+    "directory_router",
+    "prompt_router",
+    "importer_router",
+]

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

@@ -0,0 +1,21 @@
+"""V2 API routers."""
+
+from basic_memory.api.v2.routers.knowledge_router import router as knowledge_router
+from basic_memory.api.v2.routers.project_router import router as project_router
+from basic_memory.api.v2.routers.memory_router import router as memory_router
+from basic_memory.api.v2.routers.search_router import router as search_router
+from basic_memory.api.v2.routers.resource_router import router as resource_router
+from basic_memory.api.v2.routers.directory_router import router as directory_router
+from basic_memory.api.v2.routers.prompt_router import router as prompt_router
+from basic_memory.api.v2.routers.importer_router import router as importer_router
+
+__all__ = [
+    "knowledge_router",
+    "project_router",
+    "memory_router",
+    "search_router",
+    "resource_router",
+    "directory_router",
+    "prompt_router",
+    "importer_router",
+]

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

@@ -0,0 +1,93 @@
+"""V2 Directory Router - ID-based directory tree operations.
+
+This router provides directory structure browsing for projects using
+external_id UUIDs instead of name-based identifiers.
+
+Key improvements:
+- Direct project lookup via external_id UUIDs
+- Consistent with other v2 endpoints
+- Better performance through indexed queries
+"""
+
+from typing import List, Optional
+
+from fastapi import APIRouter, Query, Path
+
+from basic_memory.deps import DirectoryServiceV2ExternalDep
+from basic_memory.schemas.directory import DirectoryNode
+
+router = APIRouter(prefix="/directory", tags=["directory-v2"])
+
+
+@router.get("/tree", response_model=DirectoryNode, response_model_exclude_none=True)
+async def get_directory_tree(
+    directory_service: DirectoryServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+):
+    """Get hierarchical directory structure from the knowledge base.
+
+    Args:
+        directory_service: Service for directory operations
+        project_id: Project external UUID
+
+    Returns:
+        DirectoryNode representing the root of the hierarchical tree structure
+    """
+    # Get a hierarchical directory tree for the specific project
+    tree = await directory_service.get_directory_tree()
+
+    # Return the hierarchical tree
+    return tree
+
+
+@router.get("/structure", response_model=DirectoryNode, response_model_exclude_none=True)
+async def get_directory_structure(
+    directory_service: DirectoryServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+):
+    """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: Project external UUID
+
+    Returns:
+        DirectoryNode tree containing only folders (type="directory")
+    """
+    structure = await directory_service.get_directory_structure()
+    return structure
+
+
+@router.get("/list", response_model=List[DirectoryNode], response_model_exclude_none=True)
+async def list_directory(
+    directory_service: DirectoryServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+    dir_name: str = Query("/", description="Directory path to list"),
+    depth: int = Query(1, ge=1, le=10, description="Recursion depth (1-10)"),
+    file_name_glob: Optional[str] = Query(
+        None, description="Glob pattern for filtering file names"
+    ),
+):
+    """List directory contents with filtering and depth control.
+
+    Args:
+        directory_service: Service for directory operations
+        project_id: Project external UUID
+        dir_name: Directory path to list (default: root "/")
+        depth: Recursion depth (1-10, default: 1 for immediate children only)
+        file_name_glob: Optional glob pattern for filtering file names (e.g., "*.md", "*meeting*")
+
+    Returns:
+        List of DirectoryNode objects matching the criteria
+    """
+    # Get directory listing with filtering
+    nodes = await directory_service.list_directory(
+        dir_name=dir_name,
+        depth=depth,
+        file_name_glob=file_name_glob,
+    )
+
+    return nodes

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

@@ -0,0 +1,181 @@
+"""V2 Import Router - ID-based data import operations.
+
+This router uses v2 dependencies for consistent project handling with external_id UUIDs.
+Import endpoints use project_id in the path for consistency with other v2 endpoints.
+"""
+
+import json
+import logging
+
+from fastapi import APIRouter, Form, HTTPException, UploadFile, status, Path
+
+from basic_memory.deps import (
+    ChatGPTImporterV2ExternalDep,
+    ClaudeConversationsImporterV2ExternalDep,
+    ClaudeProjectsImporterV2ExternalDep,
+    MemoryJsonImporterV2ExternalDep,
+)
+from basic_memory.importers import Importer
+from basic_memory.schemas.importer import (
+    ChatImportResult,
+    EntityImportResult,
+    ProjectImportResult,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/import", tags=["import-v2"])
+
+
+@router.post("/chatgpt", response_model=ChatImportResult)
+async def import_chatgpt(
+    importer: ChatGPTImporterV2ExternalDep,
+    file: UploadFile,
+    project_id: str = Path(..., description="Project external UUID"),
+    folder: str = Form("conversations"),
+) -> ChatImportResult:
+    """Import conversations from ChatGPT JSON export.
+
+    Args:
+        project_id: Project external UUID from URL path
+        file: The ChatGPT conversations.json file.
+        folder: The folder to place the files in.
+        importer: ChatGPT importer instance.
+
+    Returns:
+        ChatImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    logger.info(f"V2 Importing ChatGPT conversations for project {project_id}")
+    return await import_file(importer, file, folder)
+
+
+@router.post("/claude/conversations", response_model=ChatImportResult)
+async def import_claude_conversations(
+    importer: ClaudeConversationsImporterV2ExternalDep,
+    file: UploadFile,
+    project_id: str = Path(..., description="Project external UUID"),
+    folder: str = Form("conversations"),
+) -> ChatImportResult:
+    """Import conversations from Claude conversations.json export.
+
+    Args:
+        project_id: Project external UUID from URL path
+        file: The Claude conversations.json file.
+        folder: The folder to place the files in.
+        importer: Claude conversations importer instance.
+
+    Returns:
+        ChatImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    logger.info(f"V2 Importing Claude conversations for project {project_id}")
+    return await import_file(importer, file, folder)
+
+
+@router.post("/claude/projects", response_model=ProjectImportResult)
+async def import_claude_projects(
+    importer: ClaudeProjectsImporterV2ExternalDep,
+    file: UploadFile,
+    project_id: str = Path(..., description="Project external UUID"),
+    folder: str = Form("projects"),
+) -> ProjectImportResult:
+    """Import projects from Claude projects.json export.
+
+    Args:
+        project_id: Project external UUID from URL path
+        file: The Claude projects.json file.
+        folder: The base folder to place the files in.
+        importer: Claude projects importer instance.
+
+    Returns:
+        ProjectImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    logger.info(f"V2 Importing Claude projects for project {project_id}")
+    return await import_file(importer, file, folder)
+
+
+@router.post("/memory-json", response_model=EntityImportResult)
+async def import_memory_json(
+    importer: MemoryJsonImporterV2ExternalDep,
+    file: UploadFile,
+    project_id: str = Path(..., description="Project external UUID"),
+    folder: str = Form("conversations"),
+) -> EntityImportResult:
+    """Import entities and relations from a memory.json file.
+
+    Args:
+        project_id: Project external UUID from URL path
+        file: The memory.json file.
+        folder: Optional destination folder within the project.
+        importer: Memory JSON importer instance.
+
+    Returns:
+        EntityImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    logger.info(f"V2 Importing memory.json for project {project_id}")
+    try:
+        file_data = []
+        file_bytes = await file.read()
+        file_str = file_bytes.decode("utf-8")
+        for line in file_str.splitlines():
+            json_data = json.loads(line)
+            file_data.append(json_data)
+
+        result = await importer.import_data(file_data, folder)
+        if not result.success:  # pragma: no cover
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=result.error_message or "Import failed",
+            )
+    except Exception as e:
+        logger.exception("V2 Import failed")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Import failed: {str(e)}",
+        )
+    return result
+
+
+async def import_file(importer: Importer, file: UploadFile, destination_folder: str):
+    """Helper function to import a file using an importer instance.
+
+    Args:
+        importer: The importer instance to use
+        file: The file to import
+        destination_folder: Destination folder for imported content
+
+    Returns:
+        Import result from the importer
+
+    Raises:
+        HTTPException: If import fails
+    """
+    try:
+        # Process file
+        json_data = json.load(file.file)
+        result = await importer.import_data(json_data, destination_folder)
+        if not result.success:  # pragma: no cover
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=result.error_message or "Import failed",
+            )
+
+        return result
+
+    except Exception as e:
+        logger.exception("V2 Import failed")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Import failed: {str(e)}",
+        )

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

@@ -0,0 +1,425 @@
+"""V2 Knowledge Router - External ID-based entity operations.
+
+This router provides external_id (UUID) based CRUD operations for entities,
+using stable string UUIDs that won't change with file moves or database migrations.
+
+Key improvements:
+- Stable external UUIDs that won't change with file moves or renames
+- Better API ergonomics with consistent string identifiers
+- Direct database lookups via unique indexed column
+- Simplified caching strategies
+"""
+
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Depends, Response, Path
+from loguru import logger
+
+from basic_memory.deps import (
+    EntityServiceV2ExternalDep,
+    SearchServiceV2ExternalDep,
+    LinkResolverV2ExternalDep,
+    ProjectConfigV2ExternalDep,
+    AppConfigDep,
+    SyncServiceV2ExternalDep,
+    EntityRepositoryV2ExternalDep,
+    ProjectExternalIdPathDep,
+)
+from basic_memory.schemas import DeleteEntitiesResponse
+from basic_memory.schemas.base import Entity
+from basic_memory.schemas.request import EditEntityRequest
+from basic_memory.schemas.v2 import (
+    EntityResolveRequest,
+    EntityResolveResponse,
+    EntityResponseV2,
+    MoveEntityRequestV2,
+)
+
+router = APIRouter(prefix="/knowledge", tags=["knowledge-v2"])
+
+
+async def resolve_relations_background(sync_service, entity_id: int, entity_permalink: str) -> None:
+    """Background task to resolve relations for a specific entity.
+
+    This runs asynchronously after the API response is sent, preventing
+    long delays when creating entities with many relations.
+    """
+    try:  # pragma: no cover
+        # Only resolve relations for the newly created entity
+        await sync_service.resolve_relations(entity_id=entity_id)  # pragma: no cover
+        logger.debug(  # pragma: no cover
+            f"Background: Resolved relations for entity {entity_permalink} (id={entity_id})"
+        )
+    except Exception as e:  # pragma: no cover
+        # Log but don't fail - this is a background task
+        logger.warning(  # pragma: no cover
+            f"Background: Failed to resolve relations for entity {entity_permalink}: {e}"
+        )
+
+
+## Resolution endpoint
+
+
+@router.post("/resolve", response_model=EntityResolveResponse)
+async def resolve_identifier(
+    project_id: ProjectExternalIdPathDep,
+    data: EntityResolveRequest,
+    link_resolver: LinkResolverV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+) -> EntityResolveResponse:
+    """Resolve a string identifier (external_id, permalink, title, or path) to entity info.
+
+    This endpoint provides a bridge between v1-style identifiers and v2 external_ids.
+    Use this to convert existing references to the new UUID-based format.
+
+    Args:
+        data: Request containing the identifier to resolve
+
+    Returns:
+        Entity external_id and metadata about how it was resolved
+
+    Raises:
+        HTTPException: 404 if identifier cannot be resolved
+
+    Example:
+        POST /v2/{project_id}/knowledge/resolve
+        {"identifier": "specs/search"}
+
+        Returns:
+        {
+            "external_id": "550e8400-e29b-41d4-a716-446655440000",
+            "entity_id": 123,
+            "permalink": "specs/search",
+            "file_path": "specs/search.md",
+            "title": "Search Specification",
+            "resolution_method": "permalink"
+        }
+    """
+    logger.info(f"API v2 request: resolve_identifier for '{data.identifier}'")
+
+    # Try to resolve by external_id first
+    entity = await entity_repository.get_by_external_id(data.identifier)
+    resolution_method = "external_id" if entity else "search"
+
+    # If not found by external_id, try other resolution methods
+    if not entity:
+        entity = await link_resolver.resolve_link(data.identifier)
+        if entity:
+            # Determine resolution method
+            if entity.permalink == data.identifier:
+                resolution_method = "permalink"
+            elif entity.title == data.identifier:
+                resolution_method = "title"
+            elif entity.file_path == data.identifier:
+                resolution_method = "path"
+            else:
+                resolution_method = "search"
+
+    if not entity:
+        raise HTTPException(status_code=404, detail=f"Entity not found: '{data.identifier}'")
+
+    result = EntityResolveResponse(
+        external_id=entity.external_id,
+        entity_id=entity.id,
+        permalink=entity.permalink,
+        file_path=entity.file_path,
+        title=entity.title,
+        resolution_method=resolution_method,
+    )
+
+    logger.info(
+        f"API v2 response: resolved '{data.identifier}' to external_id={result.external_id} via {resolution_method}"
+    )
+
+    return result
+
+
+## Read endpoints
+
+
+@router.get("/entities/{entity_id}", response_model=EntityResponseV2)
+async def get_entity_by_id(
+    project_id: ProjectExternalIdPathDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    entity_id: str = Path(..., description="Entity external ID (UUID)"),
+) -> EntityResponseV2:
+    """Get an entity by its external ID (UUID).
+
+    This is the primary entity retrieval method in v2, using stable UUID
+    identifiers that won't change with file moves.
+
+    Args:
+        entity_id: External ID (UUID string)
+
+    Returns:
+        Complete entity with observations and relations
+
+    Raises:
+        HTTPException: 404 if entity not found
+    """
+    logger.info(f"API v2 request: get_entity_by_id entity_id={entity_id}")
+
+    entity = await entity_repository.get_by_external_id(entity_id)
+    if not entity:
+        raise HTTPException(
+            status_code=404, detail=f"Entity with external_id '{entity_id}' not found"
+        )
+
+    result = EntityResponseV2.model_validate(entity)
+    logger.info(f"API v2 response: external_id={entity_id}, title='{result.title}'")
+
+    return result
+
+
+## Create endpoints
+
+
+@router.post("/entities", response_model=EntityResponseV2)
+async def create_entity(
+    project_id: ProjectExternalIdPathDep,
+    data: Entity,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceV2ExternalDep,
+    search_service: SearchServiceV2ExternalDep,
+) -> EntityResponseV2:
+    """Create a new entity.
+
+    Args:
+        data: Entity data to create
+
+    Returns:
+        Created entity with generated external_id (UUID)
+    """
+    logger.info(
+        "API v2 request", endpoint="create_entity", entity_type=data.entity_type, title=data.title
+    )
+
+    entity = await entity_service.create_entity(data)
+
+    # reindex
+    await search_service.index_entity(entity, background_tasks=background_tasks)
+    result = EntityResponseV2.model_validate(entity)
+
+    logger.info(
+        f"API v2 response: endpoint='create_entity' external_id={entity.external_id}, title={result.title}, permalink={result.permalink}, status_code=201"
+    )
+    return result
+
+
+## Update endpoints
+
+
+@router.put("/entities/{entity_id}", response_model=EntityResponseV2)
+async def update_entity_by_id(
+    data: Entity,
+    response: Response,
+    background_tasks: BackgroundTasks,
+    project_id: ProjectExternalIdPathDep,
+    entity_service: EntityServiceV2ExternalDep,
+    search_service: SearchServiceV2ExternalDep,
+    sync_service: SyncServiceV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    entity_id: str = Path(..., description="Entity external ID (UUID)"),
+) -> EntityResponseV2:
+    """Update an entity by external ID.
+
+    If the entity doesn't exist, it will be created (upsert behavior).
+
+    Args:
+        entity_id: External ID (UUID string)
+        data: Updated entity data
+
+    Returns:
+        Updated entity
+    """
+    logger.info(f"API v2 request: update_entity_by_id entity_id={entity_id}")
+
+    # Check if entity exists
+    existing = await entity_repository.get_by_external_id(entity_id)
+    created = existing is None
+
+    # Perform update or create
+    entity, _ = await entity_service.create_or_update_entity(data)
+    response.status_code = 201 if created else 200
+
+    # reindex
+    await search_service.index_entity(entity, background_tasks=background_tasks)
+
+    # Schedule relation resolution for new entities
+    if created:
+        background_tasks.add_task(  # pragma: no cover
+            resolve_relations_background, sync_service, entity.id, entity.permalink or ""
+        )
+
+    result = EntityResponseV2.model_validate(entity)
+
+    logger.info(
+        f"API v2 response: external_id={entity_id}, created={created}, status_code={response.status_code}"
+    )
+    return result
+
+
+@router.patch("/entities/{entity_id}", response_model=EntityResponseV2)
+async def edit_entity_by_id(
+    data: EditEntityRequest,
+    background_tasks: BackgroundTasks,
+    project_id: ProjectExternalIdPathDep,
+    entity_service: EntityServiceV2ExternalDep,
+    search_service: SearchServiceV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    entity_id: str = Path(..., description="Entity external ID (UUID)"),
+) -> EntityResponseV2:
+    """Edit an existing entity by external ID using operations like append, prepend, etc.
+
+    Args:
+        entity_id: External ID (UUID string)
+        data: Edit operation details
+
+    Returns:
+        Updated entity
+
+    Raises:
+        HTTPException: 404 if entity not found, 400 if edit fails
+    """
+    logger.info(
+        f"API v2 request: edit_entity_by_id entity_id={entity_id}, operation='{data.operation}'"
+    )
+
+    # Verify entity exists
+    entity = await entity_repository.get_by_external_id(entity_id)
+    if not entity:  # pragma: no cover
+        raise HTTPException(
+            status_code=404, detail=f"Entity with external_id '{entity_id}' not found"
+        )
+
+    try:
+        # Edit using the entity's permalink or path
+        identifier = entity.permalink or entity.file_path
+        updated_entity = await entity_service.edit_entity(
+            identifier=identifier,
+            operation=data.operation,
+            content=data.content,
+            section=data.section,
+            find_text=data.find_text,
+            expected_replacements=data.expected_replacements,
+        )
+
+        # Reindex
+        await search_service.index_entity(updated_entity, background_tasks=background_tasks)
+
+        result = EntityResponseV2.model_validate(updated_entity)
+
+        logger.info(
+            f"API v2 response: external_id={entity_id}, operation='{data.operation}', status_code=200"
+        )
+
+        return result
+
+    except Exception as e:
+        logger.error(f"Error editing entity {entity_id}: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+## Delete endpoints
+
+
+@router.delete("/entities/{entity_id}", response_model=DeleteEntitiesResponse)
+async def delete_entity_by_id(
+    background_tasks: BackgroundTasks,
+    project_id: ProjectExternalIdPathDep,
+    entity_service: EntityServiceV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    entity_id: str = Path(..., description="Entity external ID (UUID)"),
+    search_service=Depends(lambda: None),  # Optional for now
+) -> DeleteEntitiesResponse:
+    """Delete an entity by external ID.
+
+    Args:
+        entity_id: External ID (UUID string)
+
+    Returns:
+        Deletion status
+
+    Note: Returns deleted=False if entity doesn't exist (idempotent)
+    """
+    logger.info(f"API v2 request: delete_entity_by_id entity_id={entity_id}")
+
+    entity = await entity_repository.get_by_external_id(entity_id)
+    if entity is None:
+        logger.info(f"API v2 response: external_id={entity_id} not found, deleted=False")
+        return DeleteEntitiesResponse(deleted=False)
+
+    # Delete the entity using internal ID
+    deleted = await entity_service.delete_entity(entity.id)
+
+    # Remove from search index if search service available
+    if search_service:
+        background_tasks.add_task(search_service.handle_delete, entity)  # pragma: no cover
+
+    logger.info(f"API v2 response: external_id={entity_id}, deleted={deleted}")
+
+    return DeleteEntitiesResponse(deleted=deleted)
+
+
+## Move endpoint
+
+
+@router.put("/entities/{entity_id}/move", response_model=EntityResponseV2)
+async def move_entity(
+    data: MoveEntityRequestV2,
+    background_tasks: BackgroundTasks,
+    project_id: ProjectExternalIdPathDep,
+    entity_service: EntityServiceV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    project_config: ProjectConfigV2ExternalDep,
+    app_config: AppConfigDep,
+    search_service: SearchServiceV2ExternalDep,
+    entity_id: str = Path(..., description="Entity external ID (UUID)"),
+) -> EntityResponseV2:
+    """Move an entity to a new file location.
+
+    V2 API uses external_id (UUID) in the URL path for stable references.
+    The external_id will remain stable after the move.
+
+    Args:
+        project_id: Project external ID from URL path
+        entity_id: Entity external ID from URL path (primary identifier)
+        data: Move request with destination path only
+
+    Returns:
+        Updated entity with new file path
+    """
+    logger.info(
+        f"API v2 request: move_entity entity_id={entity_id}, destination='{data.destination_path}'"
+    )
+
+    try:
+        # First, get the entity by external_id to verify it exists
+        entity = await entity_repository.get_by_external_id(entity_id)
+        if not entity:  # pragma: no cover
+            raise HTTPException(
+                status_code=404, detail=f"Entity with external_id '{entity_id}' not found"
+            )
+
+        # Move the entity using its current file path as identifier
+        moved_entity = await entity_service.move_entity(
+            identifier=entity.file_path,  # Use file path for resolution
+            destination_path=data.destination_path,
+            project_config=project_config,
+            app_config=app_config,
+        )
+
+        # Reindex at new location
+        reindexed_entity = await entity_service.link_resolver.resolve_link(data.destination_path)
+        if reindexed_entity:
+            await search_service.index_entity(reindexed_entity, background_tasks=background_tasks)
+
+        result = EntityResponseV2.model_validate(moved_entity)
+
+        logger.info(f"API v2 response: moved external_id={entity_id} to '{data.destination_path}'")
+
+        return result
+
+    except HTTPException:  # pragma: no cover
+        raise  # pragma: no cover
+    except Exception as e:
+        logger.error(f"Error moving entity: {e}")
+        raise HTTPException(status_code=400, detail=str(e))

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

@@ -0,0 +1,130 @@
+"""V2 routes for memory:// URI operations.
+
+This router uses external_id UUIDs for stable, API-friendly routing.
+V1 uses string-based project names which are less efficient and less stable.
+"""
+
+from typing import Annotated, Optional
+
+from fastapi import APIRouter, Query, Path
+from loguru import logger
+
+from basic_memory.deps import ContextServiceV2ExternalDep, EntityRepositoryV2ExternalDep
+from basic_memory.schemas.base import TimeFrame, parse_timeframe
+from basic_memory.schemas.memory import (
+    GraphContext,
+    normalize_memory_url,
+)
+from basic_memory.schemas.search import SearchItemType
+from basic_memory.api.routers.utils import to_graph_context
+
+# Note: No prefix here - it's added during registration as /v2/{project_id}/memory
+router = APIRouter(tags=["memory"])
+
+
+@router.get("/memory/recent", response_model=GraphContext)
+async def recent(
+    context_service: ContextServiceV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+    type: Annotated[list[SearchItemType] | None, Query()] = None,
+    depth: int = 1,
+    timeframe: TimeFrame = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+) -> GraphContext:
+    """Get recent activity context for a project.
+
+    Args:
+        project_id: Project external UUID from URL path
+        context_service: Context service scoped to project
+        entity_repository: Entity repository scoped to project
+        type: Types of items to include (entities, relations, observations)
+        depth: How many levels of related entities to include
+        timeframe: Time window for recent activity (e.g., "7d", "1 week")
+        page: Page number for pagination
+        page_size: Number of items per page
+        max_related: Maximum related entities to include per item
+
+    Returns:
+        GraphContext with recent activity and related entities
+    """
+    # return all types by default
+    types = (
+        [SearchItemType.ENTITY, SearchItemType.RELATION, SearchItemType.OBSERVATION]
+        if not type
+        else type
+    )
+
+    logger.debug(
+        f"V2 Getting recent context for project {project_id}: `{types}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
+    )
+    # Parse timeframe
+    since = parse_timeframe(timeframe)
+    limit = page_size
+    offset = (page - 1) * page_size
+
+    # Build context
+    context = await context_service.build_context(
+        types=types, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
+    )
+    recent_context = await to_graph_context(
+        context, entity_repository=entity_repository, page=page, page_size=page_size
+    )
+    logger.debug(f"V2 Recent context: {recent_context.model_dump_json()}")
+    return recent_context
+
+
+# get_memory_context needs to be declared last so other paths can match
+
+
+@router.get("/memory/{uri:path}", response_model=GraphContext)
+async def get_memory_context(
+    context_service: ContextServiceV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    uri: str,
+    project_id: str = Path(..., description="Project external UUID"),
+    depth: int = 1,
+    timeframe: Optional[TimeFrame] = None,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+) -> GraphContext:
+    """Get rich context from memory:// URI.
+
+    V2 supports both legacy path-based URIs and new ID-based URIs:
+    - Legacy: memory://path/to/note
+    - ID-based: memory://id/123 or memory://123
+
+    Args:
+        project_id: Project external UUID from URL path
+        context_service: Context service scoped to project
+        entity_repository: Entity repository scoped to project
+        uri: Memory URI path (e.g., "id/123", "123", or "path/to/note")
+        depth: How many levels of related entities to include
+        timeframe: Optional time window for filtering related content
+        page: Page number for pagination
+        page_size: Number of items per page
+        max_related: Maximum related entities to include
+
+    Returns:
+        GraphContext with the entity and its related context
+    """
+    logger.debug(
+        f"V2 Getting context for project {project_id}, URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
+    )
+    memory_url = normalize_memory_url(uri)
+
+    # Parse timeframe
+    since = parse_timeframe(timeframe) if timeframe else None
+    limit = page_size
+    offset = (page - 1) * page_size
+
+    # Build context
+    context = await context_service.build_context(
+        memory_url, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
+    )
+    return await to_graph_context(
+        context, entity_repository=entity_repository, page=page, page_size=page_size
+    )

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

@@ -0,0 +1,357 @@
+"""V2 Project Router - External ID-based project management operations.
+
+This router provides external_id (UUID) based CRUD operations for projects,
+using stable string UUIDs that never change (unlike integer IDs or names).
+
+Key improvements:
+- Stable external UUIDs that won't change with renames or database migrations
+- Better API ergonomics with consistent string identifiers
+- Direct database lookups via unique indexed column
+- Consistent with v2 entity operations
+"""
+
+import os
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Body, Query, Path
+from loguru import logger
+
+from basic_memory.deps import (
+    ProjectServiceDep,
+    ProjectRepositoryDep,
+)
+from basic_memory.schemas.project_info import (
+    ProjectItem,
+    ProjectStatusResponse,
+)
+from basic_memory.schemas.v2 import ProjectResolveRequest, ProjectResolveResponse
+from basic_memory.utils import normalize_project_path, generate_permalink
+
+router = APIRouter(prefix="/projects", tags=["project_management-v2"])
+
+
+@router.post("/resolve", response_model=ProjectResolveResponse)
+async def resolve_project_identifier(
+    data: ProjectResolveRequest,
+    project_repository: ProjectRepositoryDep,
+) -> ProjectResolveResponse:
+    """Resolve a project identifier (name, permalink, or external_id) to project info.
+
+    This endpoint provides efficient lookup of projects by various identifiers
+    without needing to fetch the entire project list. Supports:
+    - External ID (UUID string) - preferred stable identifier
+    - Permalink
+    - Case-insensitive name matching
+
+    Args:
+        data: Request containing the identifier to resolve
+
+    Returns:
+        Project information including the external_id (UUID)
+
+    Raises:
+        HTTPException: 404 if project not found
+
+    Example:
+        POST /v2/projects/resolve
+        {"identifier": "my-project"}
+
+        Returns:
+        {
+            "external_id": "550e8400-e29b-41d4-a716-446655440000",
+            "project_id": 1,
+            "name": "my-project",
+            "permalink": "my-project",
+            "path": "/path/to/project",
+            "is_active": true,
+            "is_default": false,
+            "resolution_method": "name"
+        }
+    """
+    logger.info(f"API v2 request: resolve_project_identifier for '{data.identifier}'")
+
+    # Generate permalink for comparison
+    identifier_permalink = generate_permalink(data.identifier)
+
+    resolution_method = "name"
+    project = None
+
+    # Try external_id first (UUID format)
+    project = await project_repository.get_by_external_id(data.identifier)
+    if project:
+        resolution_method = "external_id"
+
+    # If not found by external_id, try by permalink (exact match)
+    if not project:
+        project = await project_repository.get_by_permalink(identifier_permalink)
+        if project:
+            resolution_method = "permalink"
+
+    # If not found by permalink, try case-insensitive name search
+    if not project:
+        project = await project_repository.get_by_name_case_insensitive(data.identifier)
+        if project:
+            resolution_method = "name"  # pragma: no cover
+
+    if not project:
+        raise HTTPException(status_code=404, detail=f"Project not found: '{data.identifier}'")
+
+    return ProjectResolveResponse(
+        external_id=project.external_id,
+        project_id=project.id,
+        name=project.name,
+        permalink=generate_permalink(project.name),
+        path=normalize_project_path(project.path),
+        is_active=project.is_active if hasattr(project, "is_active") else True,
+        is_default=project.is_default or False,
+        resolution_method=resolution_method,
+    )
+
+
+@router.get("/{project_id}", response_model=ProjectItem)
+async def get_project_by_id(
+    project_repository: ProjectRepositoryDep,
+    project_id: str = Path(..., description="Project external ID (UUID)"),
+) -> ProjectItem:
+    """Get project by its external ID (UUID).
+
+    This is the primary project retrieval method in v2, using stable UUID
+    identifiers that won't change with project renames.
+
+    Args:
+        project_id: External ID (UUID string)
+
+    Returns:
+        Project information including external_id
+
+    Raises:
+        HTTPException: 404 if project not found
+
+    Example:
+        GET /v2/projects/550e8400-e29b-41d4-a716-446655440000
+    """
+    logger.info(f"API v2 request: get_project_by_id for project_id={project_id}")
+
+    project = await project_repository.get_by_external_id(project_id)
+    if not project:
+        raise HTTPException(
+            status_code=404, detail=f"Project with external_id '{project_id}' not found"
+        )
+
+    return ProjectItem(
+        id=project.id,
+        external_id=project.external_id,
+        name=project.name,
+        path=normalize_project_path(project.path),
+        is_default=project.is_default or False,
+    )
+
+
+@router.patch("/{project_id}", response_model=ProjectStatusResponse)
+async def update_project_by_id(
+    project_service: ProjectServiceDep,
+    project_repository: ProjectRepositoryDep,
+    project_id: str = Path(..., description="Project external ID (UUID)"),
+    path: Optional[str] = Body(None, description="New absolute path for the project"),
+    is_active: Optional[bool] = Body(None, description="Status of the project (active/inactive)"),
+) -> ProjectStatusResponse:
+    """Update a project's information by external ID.
+
+    Args:
+        project_id: External ID (UUID string)
+        path: Optional new absolute path for the project
+        is_active: Optional status update for the project
+
+    Returns:
+        Response confirming the project was updated
+
+    Raises:
+        HTTPException: 400 if validation fails, 404 if project not found
+
+    Example:
+        PATCH /v2/projects/550e8400-e29b-41d4-a716-446655440000
+        {"path": "/new/path"}
+    """
+    logger.info(f"API v2 request: update_project_by_id for project_id={project_id}")
+
+    try:
+        # Validate that path is absolute if provided
+        if path and not os.path.isabs(path):
+            raise HTTPException(status_code=400, detail="Path must be absolute")
+
+        # Get original project info for the response
+        old_project = await project_repository.get_by_external_id(project_id)
+        if not old_project:
+            raise HTTPException(
+                status_code=404, detail=f"Project with external_id '{project_id}' not found"
+            )
+
+        old_project_info = ProjectItem(
+            id=old_project.id,
+            external_id=old_project.external_id,
+            name=old_project.name,
+            path=old_project.path,
+            is_default=old_project.is_default or False,
+        )
+
+        # Update using project name (service layer still uses names internally)
+        if path:
+            await project_service.move_project(old_project.name, path)
+        elif is_active is not None:
+            await project_service.update_project(old_project.name, is_active=is_active)
+
+        # Get updated project info (use the same external_id)
+        updated_project = await project_repository.get_by_external_id(project_id)
+        if not updated_project:  # pragma: no cover
+            raise HTTPException(
+                status_code=404,
+                detail=f"Project with external_id '{project_id}' not found after update",
+            )
+
+        return ProjectStatusResponse(
+            message=f"Project '{updated_project.name}' updated successfully",
+            status="success",
+            default=old_project.is_default or False,
+            old_project=old_project_info,
+            new_project=ProjectItem(
+                id=updated_project.id,
+                external_id=updated_project.external_id,
+                name=updated_project.name,
+                path=updated_project.path,
+                is_default=updated_project.is_default or False,
+            ),
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))  # pragma: no cover
+
+
+@router.delete("/{project_id}", response_model=ProjectStatusResponse)
+async def delete_project_by_id(
+    project_service: ProjectServiceDep,
+    project_repository: ProjectRepositoryDep,
+    project_id: str = Path(..., description="Project external ID (UUID)"),
+    delete_notes: bool = Query(
+        False, description="If True, delete project directory from filesystem"
+    ),
+) -> ProjectStatusResponse:
+    """Delete a project by external ID.
+
+    Args:
+        project_id: External ID (UUID string)
+        delete_notes: If True, delete the project directory from the filesystem
+
+    Returns:
+        Response confirming the project was deleted
+
+    Raises:
+        HTTPException: 400 if trying to delete default project, 404 if not found
+
+    Example:
+        DELETE /v2/projects/550e8400-e29b-41d4-a716-446655440000?delete_notes=false
+    """
+    logger.info(
+        f"API v2 request: delete_project_by_id for project_id={project_id}, delete_notes={delete_notes}"
+    )
+
+    try:
+        old_project = await project_repository.get_by_external_id(project_id)
+        if not old_project:
+            raise HTTPException(
+                status_code=404, detail=f"Project with external_id '{project_id}' not found"
+            )
+
+        # Check if trying to delete the default project
+        # Use is_default from database, not ConfigManager (which doesn't work in cloud mode)
+        if old_project.is_default:
+            available_projects = await project_service.list_projects()
+            other_projects = [p.name for p in available_projects if p.external_id != project_id]
+            detail = f"Cannot delete default project '{old_project.name}'. "
+            if other_projects:
+                detail += (  # pragma: no cover
+                    f"Set another project as default first. Available: {', '.join(other_projects)}"
+                )
+            else:
+                detail += "This is the only project in your configuration."  # pragma: no cover
+            raise HTTPException(status_code=400, detail=detail)
+
+        # Delete using project name (service layer still uses names internally)
+        await project_service.remove_project(old_project.name, delete_notes=delete_notes)
+
+        return ProjectStatusResponse(
+            message=f"Project '{old_project.name}' removed successfully",
+            status="success",
+            default=False,
+            old_project=ProjectItem(
+                id=old_project.id,
+                external_id=old_project.external_id,
+                name=old_project.name,
+                path=old_project.path,
+                is_default=old_project.is_default or False,
+            ),
+            new_project=None,
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))  # pragma: no cover
+
+
+@router.put("/{project_id}/default", response_model=ProjectStatusResponse)
+async def set_default_project_by_id(
+    project_service: ProjectServiceDep,
+    project_repository: ProjectRepositoryDep,
+    project_id: str = Path(..., description="Project external ID (UUID)"),
+) -> ProjectStatusResponse:
+    """Set a project as the default project by external ID.
+
+    Args:
+        project_id: External ID (UUID string) to set as default
+
+    Returns:
+        Response confirming the project was set as default
+
+    Raises:
+        HTTPException: 404 if project not found
+
+    Example:
+        PUT /v2/projects/550e8400-e29b-41d4-a716-446655440000/default
+    """
+    logger.info(f"API v2 request: set_default_project_by_id for project_id={project_id}")
+
+    try:
+        # Get the old default project from database
+        default_project = await project_repository.get_default_project()
+        if not default_project:
+            raise HTTPException(  # pragma: no cover
+                status_code=404, detail="No default project is currently set"
+            )
+
+        # Get the new default project by external_id
+        new_default_project = await project_repository.get_by_external_id(project_id)
+        if not new_default_project:
+            raise HTTPException(
+                status_code=404, detail=f"Project with external_id '{project_id}' not found"
+            )
+
+        # Set as default using project name (service layer still uses names internally)
+        await project_service.set_default_project(new_default_project.name)
+
+        return ProjectStatusResponse(
+            message=f"Project '{new_default_project.name}' set as default successfully",
+            status="success",
+            default=True,
+            old_project=ProjectItem(
+                id=default_project.id,
+                external_id=default_project.external_id,
+                name=default_project.name,
+                path=default_project.path,
+                is_default=False,
+            ),
+            new_project=ProjectItem(
+                id=new_default_project.id,
+                external_id=new_default_project.external_id,
+                name=new_default_project.name,
+                path=new_default_project.path,
+                is_default=True,
+            ),
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))  # pragma: no cover

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

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

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

@@ -0,0 +1,289 @@
+"""V2 Resource Router - ID-based resource content operations.
+
+This router uses entity external_ids (UUIDs) for all operations, with file paths
+in request bodies when needed. This is consistent with v2's external_id-first design.
+
+Key differences from v1:
+- Uses UUID external_ids in URL paths instead of integer IDs or file paths
+- File paths are in request bodies for create/update operations
+- More RESTful: POST for create, PUT for update, GET for read
+"""
+
+import uuid
+from pathlib import Path as PathLib
+
+from fastapi import APIRouter, HTTPException, Response, Path
+from loguru import logger
+
+from basic_memory.deps import (
+    ProjectConfigV2ExternalDep,
+    FileServiceV2ExternalDep,
+    EntityRepositoryV2ExternalDep,
+    SearchServiceV2ExternalDep,
+)
+from basic_memory.models.knowledge import Entity as EntityModel
+from basic_memory.schemas.v2.resource import (
+    CreateResourceRequest,
+    UpdateResourceRequest,
+    ResourceResponse,
+)
+from basic_memory.utils import validate_project_path
+
+router = APIRouter(prefix="/resource", tags=["resources-v2"])
+
+
+@router.get("/{entity_id}")
+async def get_resource_content(
+    config: ProjectConfigV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+    entity_id: str = Path(..., description="Entity external UUID"),
+) -> Response:
+    """Get raw resource content by entity external_id.
+
+    Args:
+        project_id: Project external UUID from URL path
+        entity_id: Entity external UUID
+        config: Project configuration
+        entity_repository: Entity repository for fetching entity data
+        file_service: File service for reading file content
+
+    Returns:
+        Response with entity content
+
+    Raises:
+        HTTPException: 404 if entity or file not found
+    """
+    logger.debug(f"V2 Getting content for project {project_id}, entity_id: {entity_id}")
+
+    # Get entity by external_id
+    entity = await entity_repository.get_by_external_id(entity_id)
+    if not entity:
+        raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
+
+    # Validate entity file path to prevent path traversal
+    project_path = PathLib(config.home)
+    if not validate_project_path(entity.file_path, project_path):
+        logger.error(  # pragma: no cover
+            f"Invalid file path in entity {entity.id}: {entity.file_path}"
+        )
+        raise HTTPException(  # pragma: no cover
+            status_code=500,
+            detail="Entity contains invalid file path",
+        )
+
+    # Check file exists via file_service (for cloud compatibility)
+    if not await file_service.exists(entity.file_path):
+        raise HTTPException(  # pragma: no cover
+            status_code=404,
+            detail=f"File not found: {entity.file_path}",
+        )
+
+    # Read content via file_service as bytes (works with both local and S3)
+    content = await file_service.read_file_bytes(entity.file_path)
+    content_type = file_service.content_type(entity.file_path)
+
+    return Response(content=content, media_type=content_type)
+
+
+@router.post("", response_model=ResourceResponse)
+async def create_resource(
+    data: CreateResourceRequest,
+    config: ProjectConfigV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    search_service: SearchServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+) -> ResourceResponse:
+    """Create a new resource file.
+
+    Args:
+        project_id: Project external UUID from URL path
+        data: Create resource request with file_path and content
+        config: Project configuration
+        file_service: File service for writing files
+        entity_repository: Entity repository for creating entities
+        search_service: Search service for indexing
+
+    Returns:
+        ResourceResponse with file information including entity_id and external_id
+
+    Raises:
+        HTTPException: 400 for invalid file paths, 409 if file already exists
+    """
+    try:
+        # Validate path to prevent path traversal attacks
+        project_path = PathLib(config.home)
+        if not validate_project_path(data.file_path, project_path):
+            logger.warning(
+                f"Invalid file path attempted: {data.file_path} in project {config.name}"
+            )
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid file path: {data.file_path}. "
+                "Path must be relative and stay within project boundaries.",
+            )
+
+        # Check if entity already exists
+        existing_entity = await entity_repository.get_by_file_path(data.file_path)
+        if existing_entity:
+            raise HTTPException(
+                status_code=409,
+                detail=f"Resource already exists at {data.file_path} with entity_id {existing_entity.external_id}. "
+                f"Use PUT /resource/{existing_entity.external_id} to update it.",
+            )
+
+        # Cloud compatibility: avoid assuming a local filesystem path.
+        # Delegate directory creation + writes to FileService (local or S3).
+        await file_service.ensure_directory(PathLib(data.file_path).parent)
+        checksum = await file_service.write_file(data.file_path, data.content)
+
+        # Get file info
+        file_metadata = await file_service.get_file_metadata(data.file_path)
+
+        # Determine file details
+        file_name = PathLib(data.file_path).name
+        content_type = file_service.content_type(data.file_path)
+        entity_type = "canvas" if data.file_path.endswith(".canvas") else "file"
+
+        # Create a new entity model
+        # Explicitly set external_id to ensure NOT NULL constraint is satisfied (fixes #512)
+        entity = EntityModel(
+            external_id=str(uuid.uuid4()),
+            title=file_name,
+            entity_type=entity_type,
+            content_type=content_type,
+            file_path=data.file_path,
+            checksum=checksum,
+            created_at=file_metadata.created_at,
+            updated_at=file_metadata.modified_at,
+        )
+        entity = await entity_repository.add(entity)
+
+        # Index the file for search
+        await search_service.index_entity(entity)  # pyright: ignore
+
+        # Return success response
+        return ResourceResponse(
+            entity_id=entity.id,
+            external_id=entity.external_id,
+            file_path=data.file_path,
+            checksum=checksum,
+            size=file_metadata.size,
+            created_at=file_metadata.created_at.timestamp(),
+            modified_at=file_metadata.modified_at.timestamp(),
+        )
+    except HTTPException:
+        # Re-raise HTTP exceptions without wrapping
+        raise
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error creating resource {data.file_path}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to create resource: {str(e)}")
+
+
+@router.put("/{entity_id}", response_model=ResourceResponse)
+async def update_resource(
+    data: UpdateResourceRequest,
+    config: ProjectConfigV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    search_service: SearchServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+    entity_id: str = Path(..., description="Entity external UUID"),
+) -> ResourceResponse:
+    """Update an existing resource by entity external_id.
+
+    Can update content and optionally move the file to a new path.
+
+    Args:
+        project_id: Project external UUID from URL path
+        entity_id: Entity external UUID of the resource to update
+        data: Update resource request with content and optional new file_path
+        config: Project configuration
+        file_service: File service for writing files
+        entity_repository: Entity repository for updating entities
+        search_service: Search service for indexing
+
+    Returns:
+        ResourceResponse with updated file information
+
+    Raises:
+        HTTPException: 404 if entity not found, 400 for invalid paths
+    """
+    try:
+        # Get existing entity by external_id
+        entity = await entity_repository.get_by_external_id(entity_id)
+        if not entity:
+            raise HTTPException(status_code=404, detail=f"Entity {entity_id} not found")
+
+        # Determine target file path
+        target_file_path = data.file_path if data.file_path else entity.file_path
+
+        # Validate path to prevent path traversal attacks
+        project_path = PathLib(config.home)
+        if not validate_project_path(target_file_path, project_path):
+            logger.warning(
+                f"Invalid file path attempted: {target_file_path} in project {config.name}"
+            )
+            raise HTTPException(
+                status_code=400,
+                detail=f"Invalid file path: {target_file_path}. "
+                "Path must be relative and stay within project boundaries.",
+            )
+
+        # If moving file, handle the move
+        if data.file_path and data.file_path != entity.file_path:
+            # Ensure new parent directory exists (no-op for S3)
+            await file_service.ensure_directory(PathLib(target_file_path).parent)
+
+            # If old file exists, remove it via file_service (for cloud compatibility)
+            if await file_service.exists(entity.file_path):
+                await file_service.delete_file(entity.file_path)
+        else:
+            # Ensure directory exists for in-place update
+            await file_service.ensure_directory(PathLib(target_file_path).parent)
+
+        # Write content to target file
+        checksum = await file_service.write_file(target_file_path, data.content)
+
+        # Get file info
+        file_metadata = await file_service.get_file_metadata(target_file_path)
+
+        # Determine file details
+        file_name = PathLib(target_file_path).name
+        content_type = file_service.content_type(target_file_path)
+        entity_type = "canvas" if target_file_path.endswith(".canvas") else "file"
+
+        # Update entity using internal ID
+        updated_entity = await entity_repository.update(
+            entity.id,
+            {
+                "title": file_name,
+                "entity_type": entity_type,
+                "content_type": content_type,
+                "file_path": target_file_path,
+                "checksum": checksum,
+                "updated_at": file_metadata.modified_at,
+            },
+        )
+
+        # Index the updated file for search
+        await search_service.index_entity(updated_entity)  # pyright: ignore
+
+        # Return success response
+        return ResourceResponse(
+            entity_id=entity.id,
+            external_id=entity.external_id,
+            file_path=target_file_path,
+            checksum=checksum,
+            size=file_metadata.size,
+            created_at=file_metadata.created_at.timestamp(),
+            modified_at=file_metadata.modified_at.timestamp(),
+        )
+    except HTTPException:
+        # Re-raise HTTP exceptions without wrapping
+        raise
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error updating resource {entity_id}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to update resource: {str(e)}")

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

@@ -0,0 +1,73 @@
+"""V2 router for search operations.
+
+This router uses external_id UUIDs for stable, API-friendly routing.
+V1 uses string-based project names which are less efficient and less stable.
+"""
+
+from fastapi import APIRouter, BackgroundTasks, Path
+
+from basic_memory.api.routers.utils import to_search_results
+from basic_memory.schemas.search import SearchQuery, SearchResponse
+from basic_memory.deps import SearchServiceV2ExternalDep, EntityServiceV2ExternalDep
+
+# Note: No prefix here - it's added during registration as /v2/{project_id}/search
+router = APIRouter(tags=["search"])
+
+
+@router.post("/search/", response_model=SearchResponse)
+async def search(
+    query: SearchQuery,
+    search_service: SearchServiceV2ExternalDep,
+    entity_service: EntityServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+    page: int = 1,
+    page_size: int = 10,
+):
+    """Search across all knowledge and documents in a project.
+
+    V2 uses external_id UUIDs for stable API references.
+
+    Args:
+        project_id: Project external UUID from URL path
+        query: Search query parameters (text, filters, etc.)
+        search_service: Search service scoped to project
+        entity_service: Entity service scoped to project
+        page: Page number for pagination
+        page_size: Number of results per page
+
+    Returns:
+        SearchResponse with paginated search results
+    """
+    limit = page_size
+    offset = (page - 1) * page_size
+    results = await search_service.search(query, limit=limit, offset=offset)
+    search_results = await to_search_results(entity_service, results)
+    return SearchResponse(
+        results=search_results,
+        current_page=page,
+        page_size=page_size,
+    )
+
+
+@router.post("/search/reindex")
+async def reindex(
+    background_tasks: BackgroundTasks,
+    search_service: SearchServiceV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+):
+    """Recreate and populate the search index for a project.
+
+    This is a background operation that rebuilds the search index
+    from scratch. Useful after bulk updates or if the index becomes
+    corrupted.
+
+    Args:
+        project_id: Project external UUID from URL path
+        background_tasks: FastAPI background tasks handler
+        search_service: Search service scoped to project
+
+    Returns:
+        Status message indicating reindex has been initiated
+    """
+    await search_service.reindex_all(background_tasks=background_tasks)
+    return {"status": "ok", "message": "Reindex initiated"}

src/basic_memory/cli/app.py

@@ -1,20 +1,23 @@
-from typing import Optional
+# This prevents DEBUG logs from appearing on stdout during module-level
+# initialization (e.g., template_loader.TemplateLoader() logs at DEBUG level).
+from loguru import logger
 
-import typer
+logger.remove()
 
-from basic_memory.config import get_project_config
-from basic_memory.mcp.project_session import session
+from typing import Optional  # noqa: E402
+
+import typer  # noqa: E402
+
+from basic_memory.cli.container import CliContainer, set_container  # noqa: E402
+from basic_memory.config import init_cli_logging  # noqa: E402
 
 
 def version_callback(value: bool) -> None:
     """Show version and exit."""
     if value:  # pragma: no cover
         import basic_memory
-        from basic_memory.config import config
 
         typer.echo(f"Basic Memory version: {basic_memory.__version__}")
-        typer.echo(f"Current project: {config.project}")
-        typer.echo(f"Project path: {config.home}")
         raise typer.Exit()
 
 
@@ -24,13 +27,6 @@ app = typer.Typer(name="basic-memory")
 @app.callback()
 def app_callback(
     ctx: typer.Context,
-    project: Optional[str] = typer.Option(
-        None,
-        "--project",
-        "-p",
-        help="Specify which project to use 1",
-        envvar="BASIC_MEMORY_PROJECT",
-    ),
     version: Optional[bool] = typer.Option(
         None,
         "--version",
@@ -42,32 +38,39 @@ def app_callback(
 ) -> None:
     """Basic Memory - Local-first personal knowledge management."""
 
-    # Run initialization for every command unless --version was specified
-    if not version and ctx.invoked_subcommand is not None:
-        from basic_memory.config import app_config
+    # Initialize logging for CLI (file only, no stdout)
+    init_cli_logging()
+
+    # --- Composition Root ---
+    # Create container and read config (single point of config access)
+    container = CliContainer.create()
+    set_container(container)
+
+    # Run initialization for commands that don't use the API
+    # Skip for 'mcp' command - it has its own lifespan that handles initialization
+    # Skip for API-using commands (status, sync, etc.) - they handle initialization via deps.py
+    # Skip for 'reset' command - it manages its own database lifecycle
+    skip_init_commands = {"mcp", "status", "sync", "project", "tool", "reset"}
+    if (
+        not version
+        and ctx.invoked_subcommand is not None
+        and ctx.invoked_subcommand not in skip_init_commands
+    ):
         from basic_memory.services.initialization import ensure_initialization
 
-        ensure_initialization(app_config)
-
-        # Initialize MCP session with the specified project or default
-        if project:  # pragma: no cover
-            # Use the project specified via --project flag
-            current_project_config = get_project_config(project)
-            session.set_current_project(current_project_config.name)
-
-            # Update the global config to use this project
-            from basic_memory.config import update_current_project
-
-            update_current_project(project)
-        else:
-            # Use the default project
-            current_project = app_config.default_project
-            session.set_current_project(current_project)
+        ensure_initialization(container.config)
 
 
+## import
 # Register sub-command groups
 import_app = typer.Typer(help="Import data from various sources")
 app.add_typer(import_app, name="import")
 
-claude_app = typer.Typer()
+claude_app = typer.Typer(help="Import Conversations from Claude JSON export.")
 import_app.add_typer(claude_app, name="claude")
+
+
+## cloud
+
+cloud_app = typer.Typer(help="Access Basic Memory Cloud")
+app.add_typer(cloud_app, name="cloud")

src/basic_memory/cli/auth.py

@@ -0,0 +1,300 @@
+"""WorkOS OAuth Device Authorization for CLI."""
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import time
+import webbrowser
+from contextlib import asynccontextmanager
+from collections.abc import AsyncIterator, Callable
+from typing import AsyncContextManager
+
+import httpx
+from rich.console import Console
+
+from basic_memory.config import ConfigManager
+
+console = Console()
+
+
+class CLIAuth:
+    """Handles WorkOS OAuth Device Authorization for CLI tools."""
+
+    def __init__(
+        self,
+        client_id: str,
+        authkit_domain: str,
+        http_client_factory: Callable[[], AsyncContextManager[httpx.AsyncClient]] | None = None,
+    ):
+        self.client_id = client_id
+        self.authkit_domain = authkit_domain
+        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
+        self._http_client_factory = http_client_factory
+
+    @asynccontextmanager
+    async def _get_http_client(self) -> AsyncIterator[httpx.AsyncClient]:
+        """Create an AsyncClient, optionally via injected factory.
+
+        Why: enables reliable tests without monkeypatching httpx internals while
+        still using real httpx request/response objects.
+        """
+        if self._http_client_factory:
+            async with self._http_client_factory() as client:
+                yield client
+        else:
+            async with httpx.AsyncClient() as client:
+                yield client
+
+    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."""
+        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",
+        }
+
+        try:
+            async with self._get_http_client() as client:
+                response = await client.post(device_auth_url, data=data)
+
+                if response.status_code == 200:
+                    return response.json()
+                else:
+                    console.print(
+                        f"[red]Device authorization failed: {response.status_code} - {response.text}[/red]"
+                    )
+                    return None
+        except Exception as e:
+            console.print(f"[red]Device authorization error: {e}[/red]")
+            return None
+
+    def display_user_instructions(self, device_response: dict) -> None:
+        """Display user instructions for device authorization."""
+        user_code = device_response["user_code"]
+        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("\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]")
+
+        if verification_uri_complete:
+            console.print("\nOr for one-click access, visit:")
+            console.print(f"[bold green]{verification_uri_complete}[/bold green]")
+
+            # Try to open browser automatically
+            try:
+                console.print("\n[dim]Opening browser automatically...[/dim]")
+                webbrowser.open(verification_uri_complete)
+            except Exception:
+                pass  # Silently fail if browser can't be opened
+
+        console.print("\n[dim]Waiting for you to complete authentication in your browser...[/dim]")
+
+    async def poll_for_token(self, device_code: str, interval: int = 5) -> dict | None:
+        """Poll the token endpoint until user completes authentication."""
+        token_url = f"{self.authkit_domain}/oauth2/token"
+
+        data = {
+            "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
+        current_interval = interval
+
+        for _attempt in range(max_attempts):
+            try:
+                async with self._get_http_client() as client:
+                    response = await client.post(token_url, data=data)
+
+                    if response.status_code == 200:
+                        return response.json()
+
+                    # Parse error response
+                    try:
+                        error_data = response.json()
+                        error = error_data.get("error")
+                    except Exception:
+                        error = "unknown_error"
+
+                    if error == "authorization_pending":
+                        # User hasn't completed auth yet, keep polling
+                        pass
+                    elif error == "slow_down":
+                        # Increase polling interval
+                        current_interval += 5
+                        console.print("[yellow]Slowing down polling rate...[/yellow]")
+                    elif error == "access_denied":
+                        console.print("[red]Authentication was denied by user[/red]")
+                        return None
+                    elif error == "expired_token":
+                        console.print("[red]Device code has expired. Please try again.[/red]")
+                        return None
+                    else:
+                        console.print(f"[red]Token polling error: {error}[/red]")
+                        return None
+
+            except Exception as e:
+                console.print(f"[red]Token polling request error: {e}[/red]")
+
+            # Wait before next poll
+            await self._async_sleep(current_interval)
+
+        console.print("[red]Authentication timeout. Please try again.[/red]")
+        return None
+
+    async def _async_sleep(self, seconds: int) -> None:
+        """Async sleep utility."""
+        import asyncio
+
+        await asyncio.sleep(seconds)
+
+    def save_tokens(self, tokens: dict) -> None:
+        """Save tokens to project root as .bm-auth.json."""
+        token_data = {
+            "access_token": tokens["access_token"],
+            "refresh_token": tokens.get("refresh_token"),
+            "expires_at": int(time.time()) + tokens.get("expires_in", 3600),
+            "token_type": tokens.get("token_type", "Bearer"),
+        }
+
+        with open(self.token_file, "w") as f:
+            json.dump(token_data, f, indent=2)
+
+        # Secure the token file
+        os.chmod(self.token_file, 0o600)
+
+        console.print(f"[green]Tokens saved to {self.token_file}[/green]")
+
+    def load_tokens(self) -> dict | None:
+        """Load tokens from .bm-auth.json file."""
+        if not self.token_file.exists():
+            return None
+
+        try:
+            with open(self.token_file) as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError):
+            return None
+
+    def is_token_valid(self, tokens: dict) -> bool:
+        """Check if stored token is still valid."""
+        expires_at = tokens.get("expires_at", 0)
+        # Add 60 second buffer for clock skew
+        return time.time() < (expires_at - 60)
+
+    async def refresh_token(self, refresh_token: str) -> dict | None:
+        """Refresh access token using refresh token."""
+        token_url = f"{self.authkit_domain}/oauth2/token"
+
+        data = {
+            "client_id": self.client_id,
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+        }
+
+        try:
+            async with self._get_http_client() as client:
+                response = await client.post(token_url, data=data)
+
+                if response.status_code == 200:
+                    return response.json()
+                else:
+                    console.print(
+                        f"[red]Token refresh failed: {response.status_code} - {response.text}[/red]"
+                    )
+                    return None
+        except Exception as e:
+            console.print(f"[red]Token refresh error: {e}[/red]")
+            return None
+
+    async def get_valid_token(self) -> str | None:
+        """Get valid access token, refresh if needed."""
+        tokens = self.load_tokens()
+        if not tokens:
+            return None
+
+        if self.is_token_valid(tokens):
+            return tokens["access_token"]
+
+        # Token expired - try to refresh if we have a refresh token
+        refresh_token = tokens.get("refresh_token")
+        if refresh_token:
+            console.print("[yellow]Access token expired, refreshing...[/yellow]")
+
+            new_tokens = await self.refresh_token(refresh_token)
+            if new_tokens:
+                # Save new tokens (may include rotated refresh token)
+                self.save_tokens(new_tokens)
+                console.print("[green]Token refreshed successfully[/green]")
+                return new_tokens["access_token"]
+            else:
+                console.print("[yellow]Token refresh failed. Please run 'login' again.[/yellow]")
+                return None
+        else:
+            console.print("[yellow]No refresh token available. Please run 'login' again.[/yellow]")
+            return None
+
+    async def login(self) -> bool:
+        """Perform OAuth Device Authorization login flow."""
+        console.print("[blue]Initiating authentication...[/blue]")
+
+        # Step 1: Request device authorization
+        device_response = await self.request_device_authorization()
+        if not device_response:
+            return False
+
+        # Step 2: Display user instructions
+        self.display_user_instructions(device_response)
+
+        # Step 3: Poll for token
+        device_code = device_response["device_code"]
+        interval = device_response.get("interval", 5)
+
+        tokens = await self.poll_for_token(device_code, interval)
+        if not tokens:
+            return False
+
+        # Step 4: Save tokens
+        self.save_tokens(tokens)
+
+        console.print("\n[green]Successfully authenticated with Basic Memory Cloud![/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]")
+        else:
+            console.print("[yellow]No stored authentication found[/yellow]")

src/basic_memory/cli/commands/__init__.py

@@ -1,12 +1,10 @@
 """CLI commands for basic-memory."""
 
-from . import auth, status, sync, db, import_memory_json, mcp, import_claude_conversations
-from . import import_claude_projects, import_chatgpt, tool, project
+from . import status, db, import_memory_json, mcp, import_claude_conversations
+from . import import_claude_projects, import_chatgpt, tool, project, format
 
 __all__ = [
-    "auth",
     "status",
-    "sync",
     "db",
     "import_memory_json",
     "mcp",
@@ -15,4 +13,5 @@ __all__ = [
     "import_chatgpt",
     "tool",
     "project",
+    "format",
 ]

src/basic_memory/cli/commands/auth.py

@@ -1,136 +0,0 @@
-"""OAuth management commands."""
-
-import typer
-from typing import Optional
-from pydantic import AnyHttpUrl
-
-from basic_memory.cli.app import app
-from basic_memory.mcp.auth_provider import BasicMemoryOAuthProvider
-from mcp.shared.auth import OAuthClientInformationFull
-
-
-auth_app = typer.Typer(help="OAuth client management commands")
-app.add_typer(auth_app, name="auth")
-
-
-@auth_app.command()
-def register_client(
-    client_id: Optional[str] = typer.Option(
-        None, help="Client ID (auto-generated if not provided)"
-    ),
-    client_secret: Optional[str] = typer.Option(
-        None, help="Client secret (auto-generated if not provided)"
-    ),
-    issuer_url: str = typer.Option("http://localhost:8000", help="OAuth issuer URL"),
-):
-    """Register a new OAuth client for Basic Memory MCP server."""
-
-    # Create provider instance
-    provider = BasicMemoryOAuthProvider(issuer_url=issuer_url)
-
-    # Create client info with required redirect_uris
-    client_info = OAuthClientInformationFull(
-        client_id=client_id or "",  # Provider will generate if empty
-        client_secret=client_secret or "",  # Provider will generate if empty
-        redirect_uris=[AnyHttpUrl("http://localhost:8000/callback")],  # Default redirect URI
-        client_name="Basic Memory OAuth Client",
-        grant_types=["authorization_code", "refresh_token"],
-    )
-
-    # Register the client
-    import asyncio
-
-    asyncio.run(provider.register_client(client_info))
-
-    typer.echo("Client registered successfully!")
-    typer.echo(f"Client ID: {client_info.client_id}")
-    typer.echo(f"Client Secret: {client_info.client_secret}")
-    typer.echo("\nSave these credentials securely - the client secret cannot be retrieved later.")
-
-
-@auth_app.command()
-def test_auth(
-    issuer_url: str = typer.Option("http://localhost:8000", help="OAuth issuer URL"),
-):
-    """Test OAuth authentication flow.
-
-    IMPORTANT: Use the same FASTMCP_AUTH_SECRET_KEY environment variable
-    as your MCP server for tokens to validate correctly.
-    """
-
-    import asyncio
-    import secrets
-    from mcp.server.auth.provider import AuthorizationParams
-    from pydantic import AnyHttpUrl
-
-    async def test_flow():
-        # Create provider with same secret key as server
-        provider = BasicMemoryOAuthProvider(issuer_url=issuer_url)
-
-        # Register a test client
-        client_info = OAuthClientInformationFull(
-            client_id=secrets.token_urlsafe(16),
-            client_secret=secrets.token_urlsafe(32),
-            redirect_uris=[AnyHttpUrl("http://localhost:8000/callback")],
-            client_name="Test OAuth Client",
-            grant_types=["authorization_code", "refresh_token"],
-        )
-        await provider.register_client(client_info)
-        typer.echo(f"Registered test client: {client_info.client_id}")
-
-        # Get the client
-        client = await provider.get_client(client_info.client_id)
-        if not client:
-            typer.echo("Error: Client not found after registration", err=True)
-            return
-
-        # Create authorization request
-        auth_params = AuthorizationParams(
-            state="test-state",
-            scopes=["read", "write"],
-            code_challenge="test-challenge",
-            redirect_uri=AnyHttpUrl("http://localhost:8000/callback"),
-            redirect_uri_provided_explicitly=True,
-        )
-
-        # Get authorization URL
-        auth_url = await provider.authorize(client, auth_params)
-        typer.echo(f"Authorization URL: {auth_url}")
-
-        # Extract auth code from URL
-        from urllib.parse import urlparse, parse_qs
-
-        parsed = urlparse(auth_url)
-        params = parse_qs(parsed.query)
-        auth_code = params.get("code", [None])[0]
-
-        if not auth_code:
-            typer.echo("Error: No authorization code in URL", err=True)
-            return
-
-        # Load the authorization code
-        code_obj = await provider.load_authorization_code(client, auth_code)
-        if not code_obj:
-            typer.echo("Error: Invalid authorization code", err=True)
-            return
-
-        # Exchange for tokens
-        token = await provider.exchange_authorization_code(client, code_obj)
-        typer.echo(f"Access token: {token.access_token}")
-        typer.echo(f"Refresh token: {token.refresh_token}")
-        typer.echo(f"Expires in: {token.expires_in} seconds")
-
-        # Validate access token
-        access_token_obj = await provider.load_access_token(token.access_token)
-        if access_token_obj:
-            typer.echo("Access token validated successfully!")
-            typer.echo(f"Client ID: {access_token_obj.client_id}")
-            typer.echo(f"Scopes: {access_token_obj.scopes}")
-        else:
-            typer.echo("Error: Invalid access token", err=True)
-
-    asyncio.run(test_flow())
-
-
-if __name__ == "__main__":
-    auth_app()

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

@@ -0,0 +1,6 @@
+"""Cloud commands package."""
+
+# 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

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

@@ -0,0 +1,127 @@
+"""Cloud API client utilities."""
+
+from collections.abc import AsyncIterator
+from typing import Optional
+from contextlib import asynccontextmanager
+from typing import AsyncContextManager, Callable
+
+import httpx
+import typer
+from rich.console import Console
+
+from basic_memory.cli.auth import CLIAuth
+from basic_memory.config import ConfigManager
+
+console = Console()
+
+HttpClientFactory = Callable[[], AsyncContextManager[httpx.AsyncClient]]
+
+
+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
+
+
+def get_cloud_config() -> tuple[str, str, str]:
+    """Get cloud OAuth configuration from config."""
+    config_manager = ConfigManager()
+    config = config_manager.config
+    return config.cloud_client_id, config.cloud_domain, config.cloud_host
+
+
+async def get_authenticated_headers(auth: CLIAuth | None = None) -> dict[str, str]:
+    """
+    Get authentication headers with JWT token.
+    handles jwt refresh if needed.
+    """
+    client_id, domain, _ = get_cloud_config()
+    auth_obj = auth or CLIAuth(client_id=client_id, authkit_domain=domain)
+    token = await auth_obj.get_valid_token()
+    if not token:
+        console.print("[red]Not authenticated. Please run 'basic-memory cloud login' first.[/red]")
+        raise typer.Exit(1)
+
+    return {"Authorization": f"Bearer {token}"}
+
+
+@asynccontextmanager
+async def _default_http_client(timeout: float) -> AsyncIterator[httpx.AsyncClient]:
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        yield client
+
+
+async def make_api_request(
+    method: str,
+    url: str,
+    headers: Optional[dict] = None,
+    json_data: Optional[dict] = None,
+    timeout: float = 30.0,
+    *,
+    auth: CLIAuth | None = None,
+    http_client_factory: HttpClientFactory | None = None,
+) -> httpx.Response:
+    """Make an API request to the cloud service."""
+    headers = headers or {}
+    auth_headers = await get_authenticated_headers(auth=auth)
+    headers.update(auth_headers)
+    # Add debug headers to help with compression issues
+    headers.setdefault("Accept-Encoding", "identity")  # Disable compression for debugging
+
+    client_factory = http_client_factory or (lambda: _default_http_client(timeout))
+    async with client_factory() as client:
+        try:
+            response = await client.request(method=method, url=url, headers=headers, json=json_data)
+            response.raise_for_status()
+            return response
+        except httpx.HTTPError as e:
+            # 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
+                try:
+                    error_detail = response.json()
+                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
+
+            raise CloudAPIError(f"API request failed: {e}") from e

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

@@ -0,0 +1,110 @@
+"""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()

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

@@ -0,0 +1,108 @@
+"""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(
+    *,
+    api_request=make_api_request,
+) -> 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 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,
+    *,
+    api_request=make_api_request,
+) -> 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 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, *, api_request=make_api_request) -> 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(api_request=api_request)
+        project_names = {p.name for p in projects.projects}
+        return project_name in project_names
+    except Exception:
+        return False

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

@@ -0,0 +1,193 @@
+"""Core cloud commands for Basic Memory CLI."""
+
+import typer
+from rich.console import Console
+
+from basic_memory.cli.app import cloud_app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.cli.auth import CLIAuth
+from basic_memory.config import ConfigManager
+from basic_memory.cli.commands.cloud.api_client import (
+    CloudAPIError,
+    SubscriptionRequiredError,
+    get_cloud_config,
+    make_api_request,
+)
+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,
+)
+
+console = Console()
+
+
+@cloud_app.command()
+def login():
+    """Authenticate with WorkOS using OAuth Device Authorization flow and enable cloud mode."""
+
+    async def _login():
+        client_id, domain, host_url = 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]"
+            )
+            raise typer.Exit(1)
+
+    run_with_cleanup(_login())
+
+
+@cloud_app.command()
+def logout():
+    """Disable cloud mode and return to local mode."""
+
+    # Disable cloud mode
+    config_manager = ConfigManager()
+    config = config_manager.load_config()
+    config.cloud_mode = False
+    config_manager.save_config(config)
+
+    console.print("[green]Cloud mode disabled[/green]")
+    console.print("[dim]All CLI commands now work locally[/dim]")
+
+
+@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
+
+    # Get cloud configuration
+    _, _, host_url = get_cloud_config()
+    host_url = host_url.rstrip("/")
+
+    # Prepare headers
+    headers = {}
+
+    try:
+        console.print("\n[blue]Checking cloud instance health...[/blue]")
+
+        # Make API request to check health
+        response = run_with_cleanup(
+            make_api_request(method="GET", url=f"{host_url}/proxy/health", headers=headers)
+        )
+
+        health_data = response.json()
+
+        console.print("[green]Cloud instance is healthy[/green]")
+
+        # Display status details
+        if "status" in health_data:
+            console.print(f"  Status: {health_data['status']}")
+        if "version" in health_data:
+            console.print(f"  Version: {health_data['version']}")
+        if "timestamp" in health_data:
+            console.print(f"  Timestamp: {health_data['timestamp']}")
+
+        console.print("\n[dim]To sync projects, use: bm project bisync --name <project>[/dim]")
+
+    except CloudAPIError as e:
+        console.print(f"[red]Error checking cloud health: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("setup")
+def setup() -> None:
+    """Set up cloud sync by installing rclone and configuring credentials.
+
+    After setup, use project commands for syncing:
+      bm project add <name> <path> --local-path ~/projects/<name>
+      bm project 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")
+
+    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 = run_with_cleanup(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 = run_with_cleanup(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)
+    except Exception as e:
+        console.print(f"\n[red]Unexpected error during setup: {e}[/red]")
+        raise typer.Exit(1)

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

@@ -0,0 +1,398 @@
+"""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 re
+import subprocess
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Callable, Optional, Protocol
+
+from loguru import logger
+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()
+
+# Minimum rclone version for --create-empty-src-dirs support
+MIN_RCLONE_VERSION_EMPTY_DIRS = (1, 64, 0)
+
+
+class RunResult(Protocol):
+    returncode: int
+    stdout: str
+
+
+RunFunc = Callable[..., RunResult]
+IsInstalledFunc = Callable[[], bool]
+
+
+class RcloneError(Exception):
+    """Exception raised for rclone command errors."""
+
+    pass
+
+
+def check_rclone_installed(is_installed: IsInstalledFunc = is_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_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)"
+        )
+
+
+@lru_cache(maxsize=1)
+def get_rclone_version(run: RunFunc = subprocess.run) -> tuple[int, int, int] | None:
+    """Get rclone version as (major, minor, patch) tuple.
+
+    Returns:
+        Version tuple like (1, 64, 2), or None if version cannot be determined.
+
+    Note:
+        Result is cached since rclone version won't change during runtime.
+    """
+    try:
+        result = run(["rclone", "version"], capture_output=True, text=True, timeout=10)
+        # Parse "rclone v1.64.2" or "rclone v1.60.1-DEV"
+        match = re.search(r"v(\d+)\.(\d+)\.(\d+)", result.stdout)
+        if match:
+            version = (int(match.group(1)), int(match.group(2)), int(match.group(3)))
+            logger.debug(f"Detected rclone version: {version}")
+            return version
+    except Exception as e:
+        logger.warning(f"Could not determine rclone version: {e}")
+    return None
+
+
+def supports_create_empty_src_dirs(version: tuple[int, int, int] | None) -> bool:
+    """Check if installed rclone supports --create-empty-src-dirs flag.
+
+    Returns:
+        True if rclone version >= 1.64.0, False otherwise.
+    """
+    if version is None:
+        # If we can't determine version, assume older and skip the flag
+        return False
+    return version >= MIN_RCLONE_VERSION_EMPTY_DIRS
+
+
+@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,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    filter_path: Path | None = None,
+) -> 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(is_installed=is_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 = filter_path or 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 = 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,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    version: tuple[int, int, int] | None = None,
+    filter_path: Path | None = None,
+    state_path: Path | None = None,
+    is_initialized: Callable[[str], bool] = bisync_initialized,
+) -> 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(is_installed=is_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 = filter_path or get_bmignore_filter_path()
+    state_path = state_path or 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,
+        "--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),
+    ]
+
+    # Add --create-empty-src-dirs if rclone version supports it (v1.64+)
+    version = version if version is not None else get_rclone_version(run=run)
+    if supports_create_empty_src_dirs(version):
+        cmd.append("--create-empty-src-dirs")
+
+    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 is_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 = run(cmd, text=True)
+    return result.returncode == 0
+
+
+def project_check(
+    project: SyncProject,
+    bucket_name: str,
+    one_way: bool = False,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+    filter_path: Path | None = None,
+) -> 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(is_installed=is_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 = filter_path or 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 = run(cmd, capture_output=True, text=True)
+    return result.returncode == 0
+
+
+def project_ls(
+    project: SyncProject,
+    bucket_name: str,
+    path: Optional[str] = None,
+    *,
+    run: RunFunc = subprocess.run,
+    is_installed: IsInstalledFunc = is_rclone_installed,
+) -> 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(is_installed=is_installed)
+
+    remote_path = get_project_remote(project, bucket_name)
+    if path:
+        remote_path = f"{remote_path}/{path}"
+
+    cmd = ["rclone", "ls", remote_path]
+    result = run(cmd, capture_output=True, text=True, check=True)
+    return result.stdout.splitlines()

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

@@ -0,0 +1,110 @@
+"""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.
+"""
+
+import configparser
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console
+
+console = Console()
+
+
+class RcloneConfigError(Exception):
+    """Exception raised for rclone configuration errors."""
+
+    pass
+
+
+def get_rclone_config_path() -> Path:
+    """Get the path to rclone configuration file."""
+    config_dir = Path.home() / ".config" / "rclone"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir / "rclone.conf"
+
+
+def backup_rclone_config() -> Optional[Path]:
+    """Create a backup of existing rclone config."""
+    config_path = get_rclone_config_path()
+    if not config_path.exists():
+        return None
+
+    backup_path = config_path.with_suffix(f".conf.backup-{os.getpid()}")
+    shutil.copy2(config_path, backup_path)
+    console.print(f"[dim]Created backup: {backup_path}[/dim]")
+    return backup_path
+
+
+def load_rclone_config() -> configparser.ConfigParser:
+    """Load existing rclone configuration."""
+    config = configparser.ConfigParser()
+    config_path = get_rclone_config_path()
+
+    if config_path.exists():
+        config.read(config_path)
+
+    return config
+
+
+def save_rclone_config(config: configparser.ConfigParser) -> None:
+    """Save rclone configuration to file."""
+    config_path = get_rclone_config_path()
+
+    with open(config_path, "w") as f:
+        config.write(f)
+
+    console.print(f"[dim]Updated rclone config: {config_path}[/dim]")
+
+
+def configure_rclone_remote(
+    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'.
+
+    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"
+
+    # Add/update the remote section
+    if not config.has_section(REMOTE_NAME):
+        config.add_section(REMOTE_NAME)
+
+    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

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

@@ -0,0 +1,263 @@
+"""Cross-platform rclone installation utilities."""
+
+import os
+import platform
+import shutil
+import subprocess
+from typing import Optional
+
+from rich.console import Console
+
+console = Console()
+
+
+class RcloneInstallError(Exception):
+    """Exception raised for rclone installation errors."""
+
+    pass
+
+
+def is_rclone_installed() -> bool:
+    """Check if rclone is already installed and available in PATH."""
+    return shutil.which("rclone") is not None
+
+
+def get_platform() -> str:
+    """Get the current platform identifier."""
+    system = platform.system().lower()
+    if system == "darwin":
+        return "macos"
+    elif system == "linux":
+        return "linux"
+    elif system == "windows":
+        return "windows"
+    else:
+        raise RcloneInstallError(f"Unsupported platform: {system}")
+
+
+def run_command(command: list[str], check: bool = True) -> subprocess.CompletedProcess:
+    """Run a command with proper error handling."""
+    try:
+        console.print(f"[dim]Running: {' '.join(command)}[/dim]")
+        result = subprocess.run(command, capture_output=True, text=True, check=check)
+        if result.stdout:
+            console.print(f"[dim]Output: {result.stdout.strip()}[/dim]")
+        return result
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]Command failed: {e}[/red]")
+        if e.stderr:
+            console.print(f"[red]Error output: {e.stderr}[/red]")
+        raise RcloneInstallError(f"Command failed: {e}") from e
+    except FileNotFoundError as e:
+        raise RcloneInstallError(f"Command not found: {' '.join(command)}") from e
+
+
+def install_rclone_macos() -> None:
+    """Install rclone on macOS using Homebrew or official script."""
+    # Try Homebrew first
+    if shutil.which("brew"):
+        try:
+            console.print("[blue]Installing rclone via Homebrew...[/blue]")
+            run_command(["brew", "install", "rclone"])
+            console.print("[green]rclone installed via Homebrew[/green]")
+            return
+        except RcloneInstallError:
+            console.print(
+                "[yellow]Homebrew installation failed, trying official script...[/yellow]"
+            )
+
+    # Fallback to official script
+    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]")
+    except RcloneInstallError:
+        raise RcloneInstallError(
+            "Failed to install rclone. Please install manually: brew install rclone"
+        )
+
+
+def install_rclone_linux() -> None:
+    """Install rclone on Linux using package managers or official script."""
+    # Try snap first (most universal)
+    if shutil.which("snap"):
+        try:
+            console.print("[blue]Installing rclone via snap...[/blue]")
+            run_command(["sudo", "snap", "install", "rclone"])
+            console.print("[green]rclone installed via snap[/green]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]Snap installation failed, trying apt...[/yellow]")
+
+    # Try apt (Debian/Ubuntu)
+    if shutil.which("apt"):
+        try:
+            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]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]apt installation failed, trying official script...[/yellow]")
+
+    # Fallback to official script
+    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]")
+    except RcloneInstallError:
+        raise RcloneInstallError(
+            "Failed to install rclone. Please install manually: sudo snap install rclone"
+        )
+
+
+def install_rclone_windows() -> None:
+    """Install rclone on Windows using package managers."""
+    # Try winget first (built into Windows 10+)
+    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]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]winget installation failed, trying chocolatey...[/yellow]")
+
+    # Try chocolatey
+    if shutil.which("choco"):
+        try:
+            console.print("[blue]Installing rclone via chocolatey...[/blue]")
+            run_command(["choco", "install", "rclone", "-y"])
+            console.print("[green]rclone installed via chocolatey[/green]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]chocolatey installation failed, trying scoop...[/yellow]")
+
+    # Try scoop
+    if shutil.which("scoop"):
+        try:
+            console.print("[blue]Installing rclone via scoop...[/blue]")
+            run_command(["scoop", "install", "rclone"])
+            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"
+    )
+    raise RcloneInstallError(error_msg)
+
+
+def install_rclone(platform_override: Optional[str] = None) -> None:
+    """Install rclone for the current platform."""
+    if is_rclone_installed():
+        console.print("[green]rclone is already installed[/green]")
+        return
+
+    platform_name = platform_override or get_platform()
+    console.print(f"[blue]Installing rclone for {platform_name}...[/blue]")
+
+    try:
+        if platform_name == "macos":
+            install_rclone_macos()
+        elif platform_name == "linux":
+            install_rclone_linux()
+        elif platform_name == "windows":
+            install_rclone_windows()
+            refresh_windows_path()
+        else:
+            raise RcloneInstallError(f"Unsupported platform: {platform_name}")
+
+        # Verify installation
+        if not is_rclone_installed():
+            raise RcloneInstallError("rclone installation completed but command not found in PATH")
+
+        console.print("[green]rclone installation completed successfully[/green]")
+
+    except RcloneInstallError:
+        raise
+    except Exception as e:
+        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():
+        return None
+
+    try:
+        result = run_command(["rclone", "version"], check=False)
+        if result.returncode == 0:
+            # Parse version from output (format: "rclone v1.64.0")
+            lines = result.stdout.strip().split("\n")
+            for line in lines:
+                if line.startswith("rclone v"):
+                    return line.split()[1]
+        return "unknown"
+    except Exception:
+        return "unknown"

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

@@ -0,0 +1,240 @@
+"""WebDAV upload functionality for basic-memory projects."""
+
+import os
+from pathlib import Path
+from contextlib import AbstractAsyncContextManager
+from typing import Callable
+
+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,
+    *,
+    client_cm_factory: Callable[[], AbstractAsyncContextManager[httpx.AsyncClient]] | None = None,
+    put_func=call_put,
+) -> 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.
+            # Allow injection for tests (MockTransport) while keeping production default.
+            cm_factory = client_cm_factory or get_client
+            async with cm_factory() 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 put_func(
+                        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

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

@@ -0,0 +1,124 @@
+"""Upload CLI commands for basic-memory projects."""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from basic_memory.cli.app import cloud_app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.cli.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]")
+
+    run_with_cleanup(_upload())

src/basic_memory/cli/commands/command_utils.py

@@ -0,0 +1,99 @@
+"""utility functions for commands"""
+
+import asyncio
+from typing import Optional, TypeVar, Coroutine, Any
+
+from mcp.server.fastmcp.exceptions import ToolError
+import typer
+
+from rich.console import Console
+
+from basic_memory import db
+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()
+
+T = TypeVar("T")
+
+
+def run_with_cleanup(coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine with proper database cleanup.
+
+    This helper ensures database connections are cleaned up before the
+    event loop closes, preventing process hangs in CLI commands.
+
+    Args:
+        coro: The coroutine to run
+
+    Returns:
+        The result of the coroutine
+    """
+
+    async def _with_cleanup() -> T:
+        try:
+            return await coro
+        finally:
+            await db.shutdown_db()
+
+    return asyncio.run(_with_cleanup())
+
+
+async def run_sync(
+    project: Optional[str] = None,
+    force_full: bool = False,
+    run_in_background: bool = True,
+):
+    """Run sync operation via API endpoint.
+
+    Args:
+        project: Optional project name
+        force_full: If True, force a full scan bypassing watermark optimization
+        run_in_background: If True, return immediately; if False, wait for completion
+    """
+
+    try:
+        async with get_client() as client:
+            project_item = await get_active_project(client, project, None)
+            url = f"{project_item.project_url}/project/sync"
+            params = []
+            if force_full:
+                params.append("force_full=true")
+            if not run_in_background:
+                params.append("run_in_background=false")
+            if params:
+                url += "?" + "&".join(params)
+            response = await call_post(client, url)
+            data = response.json()
+            # Background mode returns {"message": "..."}, foreground returns SyncReportResponse
+            if "message" in data:
+                console.print(f"[green]{data['message']}[/green]")
+            else:
+                # Foreground mode - show summary of sync results
+                total = data.get("total", 0)
+                new_count = len(data.get("new", []))
+                modified_count = len(data.get("modified", []))
+                deleted_count = len(data.get("deleted", []))
+                console.print(
+                    f"[green]Synced {total} files[/green] "
+                    f"(new: {new_count}, modified: {modified_count}, deleted: {deleted_count})"
+                )
+    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)

src/basic_memory/cli/commands/db.py

@@ -1,14 +1,50 @@
 """Database management commands."""
 
-import asyncio
 from pathlib import Path
 
 import typer
 from loguru import logger
+from rich.console import Console
+from sqlalchemy.exc import OperationalError
 
 from basic_memory import db
 from basic_memory.cli.app import app
-from basic_memory.config import app_config, config_manager
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.config import ConfigManager
+from basic_memory.repository import ProjectRepository
+from basic_memory.services.initialization import reconcile_projects_with_config
+from basic_memory.sync.sync_service import get_sync_service
+
+console = Console()
+
+
+async def _reindex_projects(app_config):
+    """Reindex all projects in a single async context.
+
+    This ensures all database operations use the same event loop,
+    and proper cleanup happens when the function completes.
+    """
+    try:
+        await reconcile_projects_with_config(app_config)
+
+        # Get database session (migrations already run if needed)
+        _, session_maker = await db.get_or_create_db(
+            db_path=app_config.database_path,
+            db_type=db.DatabaseType.FILESYSTEM,
+        )
+        project_repository = ProjectRepository(session_maker)
+        projects = await project_repository.get_active_projects()
+
+        for project in projects:
+            console.print(f"  Indexing [cyan]{project.name}[/cyan]...")
+            logger.info(f"Starting sync for project: {project.name}")
+            sync_service = await get_sync_service(project)
+            sync_dir = Path(project.path)
+            await sync_service.sync(sync_dir, project_name=project.name)
+            logger.info(f"Sync completed for project: {project.name}")
+    finally:
+        # Clean up database connections before event loop closes
+        await db.shutdown_db()
 
 
 @app.command()
@@ -16,29 +52,54 @@ def reset(
     reindex: bool = typer.Option(False, "--reindex", help="Rebuild db index from filesystem"),
 ):  # pragma: no cover
     """Reset database (drop all tables and recreate)."""
-    if typer.confirm("This will delete all data in your db. Are you sure?"):
+    console.print(
+        "[yellow]Note:[/yellow] This only deletes the index database. "
+        "Your markdown note files will not be affected.\n"
+        "Use [green]bm reset --reindex[/green] to automatically rebuild the index afterward."
+    )
+    if typer.confirm("Reset the database index?"):
         logger.info("Resetting database...")
+        config_manager = ConfigManager()
+        app_config = config_manager.config
         # Get database path
         db_path = app_config.app_database_path
 
-        # Delete the database file if it exists
-        if db_path.exists():
-            db_path.unlink()
-            logger.info(f"Database file deleted: {db_path}")
+        # Delete the database file and WAL files if they exist
+        for suffix in ["", "-shm", "-wal"]:
+            path = db_path.parent / f"{db_path.name}{suffix}"
+            if path.exists():
+                try:
+                    path.unlink()
+                    logger.info(f"Deleted: {path}")
+                except OSError as e:
+                    console.print(
+                        f"[red]Error:[/red] Cannot delete {path.name}: {e}\n"
+                        "The database may be in use by another process (e.g., MCP server).\n"
+                        "Please close Claude Desktop or any other Basic Memory clients and try again."
+                    )
+                    raise typer.Exit(1)
 
-        # Reset project configuration
-        config_manager.config.projects = {"main": str(Path.home() / "basic-memory")}
-        config_manager.config.default_project = "main"
-        config_manager.save_config(config_manager.config)
-        logger.info("Project configuration reset to default")
-
-        # Create a new empty database
-        asyncio.run(db.run_migrations(app_config))
-        logger.info("Database reset complete")
+        # Create a new empty database (preserves project configuration)
+        try:
+            run_with_cleanup(db.run_migrations(app_config))
+        except OperationalError as e:
+            if "disk I/O error" in str(e) or "database is locked" in str(e):
+                console.print(
+                    "[red]Error:[/red] Cannot access database. "
+                    "It may be in use by another process (e.g., MCP server).\n"
+                    "Please close Claude Desktop or any other Basic Memory clients and try again."
+                )
+                raise typer.Exit(1)
+            raise
+        console.print("[green]Database reset complete[/green]")
 
         if reindex:
-            # Import and run sync
-            from basic_memory.cli.commands.sync import sync
-
-            logger.info("Rebuilding search index from filesystem...")
-            sync(watch=False)  # pyright: ignore
+            projects = list(app_config.projects)
+            if not projects:
+                console.print("[yellow]No projects configured. Skipping reindex.[/yellow]")
+            else:
+                console.print(f"Rebuilding search index for {len(projects)} project(s)...")
+                # Note: _reindex_projects has its own cleanup, but run_with_cleanup
+                # ensures db.shutdown_db() is called even if _reindex_projects changes
+                run_with_cleanup(_reindex_projects(app_config))
+                console.print("[green]Reindex complete[/green]")

src/basic_memory/cli/commands/format.py

@@ -0,0 +1,198 @@
+"""Format command for basic-memory CLI."""
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from loguru import logger
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from basic_memory.cli.app import app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.config import ConfigManager, get_project_config
+from basic_memory.file_utils import format_file
+
+console = Console()
+
+
+def is_markdown_extension(path: Path) -> bool:
+    """Check if file has a markdown extension."""
+    return path.suffix.lower() in (".md", ".markdown")
+
+
+async def format_single_file(file_path: Path, app_config) -> tuple[Path, bool, Optional[str]]:
+    """Format a single file.
+
+    Returns:
+        Tuple of (path, success, error_message)
+    """
+    try:
+        result = await format_file(
+            file_path, app_config, is_markdown=is_markdown_extension(file_path)
+        )
+        if result is not None:
+            return (file_path, True, None)
+        else:
+            return (file_path, False, "No formatter configured or formatting skipped")
+    except Exception as e:
+        return (file_path, False, str(e))
+
+
+async def format_files(
+    paths: list[Path], app_config, show_progress: bool = True
+) -> tuple[int, int, list[tuple[Path, str]]]:
+    """Format multiple files.
+
+    Returns:
+        Tuple of (formatted_count, skipped_count, errors)
+    """
+    formatted = 0
+    skipped = 0
+    errors: list[tuple[Path, str]] = []
+
+    if show_progress:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            task = progress.add_task("Formatting files...", total=len(paths))
+
+            for file_path in paths:
+                path, success, error = await format_single_file(file_path, app_config)
+                if success:
+                    formatted += 1
+                elif error and "No formatter configured" not in error:
+                    errors.append((path, error))
+                else:
+                    skipped += 1
+                progress.update(task, advance=1)
+    else:
+        for file_path in paths:
+            path, success, error = await format_single_file(file_path, app_config)
+            if success:
+                formatted += 1
+            elif error and "No formatter configured" not in error:
+                errors.append((path, error))
+            else:
+                skipped += 1
+
+    return formatted, skipped, errors
+
+
+async def run_format(
+    path: Optional[Path] = None,
+    project: Optional[str] = None,
+) -> None:
+    """Run the format command."""
+    app_config = ConfigManager().config
+
+    # Check if formatting is enabled
+    if (
+        not app_config.format_on_save
+        and not app_config.formatter_command
+        and not app_config.formatters
+    ):
+        console.print(
+            "[yellow]No formatters configured. Set format_on_save=true and "
+            "formatter_command or formatters in your config.[/yellow]"
+        )
+        console.print(
+            "\nExample config (~/.basic-memory/config.json):\n"
+            '  "format_on_save": true,\n'
+            '  "formatter_command": "prettier --write {file}"\n'
+        )
+        raise typer.Exit(1)
+
+    # Temporarily enable format_on_save for this command
+    # (so format_file actually runs the formatter)
+    original_format_on_save = app_config.format_on_save
+    app_config.format_on_save = True
+
+    try:
+        # Determine which files to format
+        if path:
+            # Format specific file or directory
+            if path.is_file():
+                files = [path]
+            elif path.is_dir():
+                # Find all markdown and json files
+                files = (
+                    list(path.rglob("*.md"))
+                    + list(path.rglob("*.json"))
+                    + list(path.rglob("*.canvas"))
+                )
+            else:
+                console.print(f"[red]Path not found: {path}[/red]")
+                raise typer.Exit(1)
+        else:
+            # Format all files in project
+            project_config = get_project_config(project)
+            project_path = Path(project_config.home)
+
+            if not project_path.exists():
+                console.print(f"[red]Project path not found: {project_path}[/red]")
+                raise typer.Exit(1)
+
+            # Find all markdown and json files
+            files = (
+                list(project_path.rglob("*.md"))
+                + list(project_path.rglob("*.json"))
+                + list(project_path.rglob("*.canvas"))
+            )
+
+        if not files:
+            console.print("[yellow]No files found to format.[/yellow]")
+            return
+
+        console.print(f"Found {len(files)} file(s) to format...")
+
+        formatted, skipped, errors = await format_files(files, app_config)
+
+        # Print summary
+        console.print()
+        if formatted > 0:
+            console.print(f"[green]Formatted: {formatted} file(s)[/green]")
+        if skipped > 0:
+            console.print(f"[dim]Skipped: {skipped} file(s) (no formatter for extension)[/dim]")
+        if errors:
+            console.print(f"[red]Errors: {len(errors)} file(s)[/red]")
+            for path, error in errors:
+                console.print(f"  [red]{path}[/red]: {error}")
+
+    finally:
+        # Restore original setting
+        app_config.format_on_save = original_format_on_save
+
+
+@app.command()
+def format(
+    path: Annotated[
+        Optional[Path],
+        typer.Argument(help="File or directory to format. Defaults to current project."),
+    ] = None,
+    project: Annotated[
+        Optional[str],
+        typer.Option("--project", "-p", help="Project name to format."),
+    ] = None,
+) -> None:
+    """Format files using configured formatters.
+
+    Uses the formatter_command or formatters settings from your config.
+    By default, formats all .md, .json, and .canvas files in the current project.
+
+    Examples:
+        basic-memory format                    # Format all files in current project
+        basic-memory format --project research # Format files in specific project
+        basic-memory format notes/meeting.md   # Format a specific file
+        basic-memory format notes/             # Format all files in directory
+    """
+    try:
+        run_with_cleanup(run_format(path, project))
+    except Exception as e:
+        if not isinstance(e, typer.Exit):
+            logger.error(f"Error formatting files: {e}")
+            console.print(f"[red]Error formatting files: {e}[/red]")
+            raise typer.Exit(code=1)
+        raise

src/basic_memory/cli/commands/import_chatgpt.py

@@ -1,15 +1,16 @@
 """Import command for ChatGPT conversations."""
 
-import asyncio
 import json
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import import_app
-from basic_memory.config import config
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.importers import ChatGPTImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.services.file_service import FileService
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
@@ -17,10 +18,14 @@ from rich.panel import Panel
 console = Console()
 
 
-async def get_markdown_processor() -> MarkdownProcessor:
-    """Get MarkdownProcessor instance."""
+async def get_importer_dependencies() -> Tuple[MarkdownProcessor, FileService]:
+    """Get MarkdownProcessor and FileService instances for importers."""
+    config = get_project_config()
+    app_config = ConfigManager().config
     entity_parser = EntityParser(config.home)
-    return MarkdownProcessor(entity_parser)
+    markdown_processor = MarkdownProcessor(entity_parser, app_config=app_config)
+    file_service = FileService(config.home, markdown_processor, app_config=app_config)
+    return markdown_processor, file_service
 
 
 @import_app.command(name="chatgpt", help="Import conversations from ChatGPT JSON export.")
@@ -47,18 +52,18 @@ def import_chatgpt(
             typer.echo(f"Error: File not found: {conversations_json}", err=True)
             raise typer.Exit(1)
 
-        # Get markdown processor
-        markdown_processor = asyncio.run(get_markdown_processor())
-
+        # Get importer dependencies
+        markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
+        config = get_project_config()
         # Process the file
         base_path = config.home / folder
         console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
 
         # Create importer and run import
-        importer = ChatGPTImporter(config.home, markdown_processor)
+        importer = ChatGPTImporter(config.home, markdown_processor, file_service)
         with conversations_json.open("r", encoding="utf-8") as file:
             json_data = json.load(file)
-            result = asyncio.run(importer.import_data(json_data, folder))
+            result = run_with_cleanup(importer.import_data(json_data, folder))
 
         if not result.success:  # pragma: no cover
             typer.echo(f"Error during import: {result.error_message}", err=True)

src/basic_memory/cli/commands/import_claude_conversations.py

@@ -1,15 +1,16 @@
 """Import command for basic-memory CLI to import chat data from conversations2.json format."""
 
-import asyncio
 import json
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import claude_app
-from basic_memory.config import config
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.importers.claude_conversations_importer import ClaudeConversationsImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.services.file_service import FileService
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
@@ -17,10 +18,14 @@ from rich.panel import Panel
 console = Console()
 
 
-async def get_markdown_processor() -> MarkdownProcessor:
-    """Get MarkdownProcessor instance."""
+async def get_importer_dependencies() -> Tuple[MarkdownProcessor, FileService]:
+    """Get MarkdownProcessor and FileService instances for importers."""
+    config = get_project_config()
+    app_config = ConfigManager().config
     entity_parser = EntityParser(config.home)
-    return MarkdownProcessor(entity_parser)
+    markdown_processor = MarkdownProcessor(entity_parser, app_config=app_config)
+    file_service = FileService(config.home, markdown_processor, app_config=app_config)
+    return markdown_processor, file_service
 
 
 @claude_app.command(name="conversations", help="Import chat conversations from Claude.ai.")
@@ -42,16 +47,17 @@ def import_claude(
     After importing, run 'basic-memory sync' to index the new files.
     """
 
+    config = get_project_config()
     try:
         if not conversations_json.exists():
             typer.echo(f"Error: File not found: {conversations_json}", err=True)
             raise typer.Exit(1)
 
-        # Get markdown processor
-        markdown_processor = asyncio.run(get_markdown_processor())
+        # Get importer dependencies
+        markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = ClaudeConversationsImporter(config.home, markdown_processor)
+        importer = ClaudeConversationsImporter(config.home, markdown_processor, file_service)
 
         # Process the file
         base_path = config.home / folder
@@ -60,7 +66,7 @@ def import_claude(
         # Run the import
         with conversations_json.open("r", encoding="utf-8") as file:
             json_data = json.load(file)
-            result = asyncio.run(importer.import_data(json_data, folder))
+            result = run_with_cleanup(importer.import_data(json_data, folder))
 
         if not result.success:  # pragma: no cover
             typer.echo(f"Error during import: {result.error_message}", err=True)

src/basic_memory/cli/commands/import_claude_projects.py

@@ -1,15 +1,16 @@
 """Import command for basic-memory CLI to import project data from Claude.ai."""
 
-import asyncio
 import json
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import claude_app
-from basic_memory.config import config
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.importers.claude_projects_importer import ClaudeProjectsImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.services.file_service import FileService
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
@@ -17,10 +18,14 @@ from rich.panel import Panel
 console = Console()
 
 
-async def get_markdown_processor() -> MarkdownProcessor:
-    """Get MarkdownProcessor instance."""
+async def get_importer_dependencies() -> Tuple[MarkdownProcessor, FileService]:
+    """Get MarkdownProcessor and FileService instances for importers."""
+    config = get_project_config()
+    app_config = ConfigManager().config
     entity_parser = EntityParser(config.home)
-    return MarkdownProcessor(entity_parser)
+    markdown_processor = MarkdownProcessor(entity_parser, app_config=app_config)
+    file_service = FileService(config.home, markdown_processor, app_config=app_config)
+    return markdown_processor, file_service
 
 
 @claude_app.command(name="projects", help="Import projects from Claude.ai.")
@@ -41,16 +46,17 @@ def import_projects(
 
     After importing, run 'basic-memory sync' to index the new files.
     """
+    config = get_project_config()
     try:
         if not projects_json.exists():
             typer.echo(f"Error: File not found: {projects_json}", err=True)
             raise typer.Exit(1)
 
-        # Get markdown processor
-        markdown_processor = asyncio.run(get_markdown_processor())
+        # Get importer dependencies
+        markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = ClaudeProjectsImporter(config.home, markdown_processor)
+        importer = ClaudeProjectsImporter(config.home, markdown_processor, file_service)
 
         # Process the file
         base_path = config.home / base_folder if base_folder else config.home
@@ -59,7 +65,7 @@ def import_projects(
         # Run the import
         with projects_json.open("r", encoding="utf-8") as file:
             json_data = json.load(file)
-            result = asyncio.run(importer.import_data(json_data, base_folder))
+            result = run_with_cleanup(importer.import_data(json_data, base_folder))
 
         if not result.success:  # pragma: no cover
             typer.echo(f"Error during import: {result.error_message}", err=True)

src/basic_memory/cli/commands/import_memory_json.py

@@ -1,15 +1,16 @@
 """Import command for basic-memory CLI to import from JSON memory format."""
 
-import asyncio
 import json
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import import_app
-from basic_memory.config import config
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.importers.memory_json_importer import MemoryJsonImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
+from basic_memory.services.file_service import FileService
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
@@ -17,10 +18,14 @@ from rich.panel import Panel
 console = Console()
 
 
-async def get_markdown_processor() -> MarkdownProcessor:
-    """Get MarkdownProcessor instance."""
+async def get_importer_dependencies() -> Tuple[MarkdownProcessor, FileService]:
+    """Get MarkdownProcessor and FileService instances for importers."""
+    config = get_project_config()
+    app_config = ConfigManager().config
     entity_parser = EntityParser(config.home)
-    return MarkdownProcessor(entity_parser)
+    markdown_processor = MarkdownProcessor(entity_parser, app_config=app_config)
+    file_service = FileService(config.home, markdown_processor, app_config=app_config)
+    return markdown_processor, file_service
 
 
 @import_app.command()
@@ -38,20 +43,19 @@ def memory_json(
     1. Read entities and relations from the JSON file
     2. Create markdown files for each entity
     3. Include outgoing relations in each entity's markdown
-
-    After importing, run 'basic-memory sync' to index the new files.
     """
 
     if not json_path.exists():
         typer.echo(f"Error: File not found: {json_path}", err=True)
         raise typer.Exit(1)
 
+    config = get_project_config()
     try:
-        # Get markdown processor
-        markdown_processor = asyncio.run(get_markdown_processor())
+        # Get importer dependencies
+        markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = MemoryJsonImporter(config.home, markdown_processor)
+        importer = MemoryJsonImporter(config.home, markdown_processor, file_service)
 
         # Process the file
         base_path = config.home if not destination_folder else config.home / destination_folder
@@ -63,7 +67,7 @@ def memory_json(
             for line in file:
                 json_data = json.loads(line)
                 file_data.append(json_data)
-        result = asyncio.run(importer.import_data(file_data, destination_folder))
+        result = run_with_cleanup(importer.import_data(file_data, destination_folder))
 
         if not result.success:  # pragma: no cover
             typer.echo(f"Error during import: {result.error_message}", err=True)
@@ -74,13 +78,12 @@ def memory_json(
             Panel(
                 f"[green]Import complete![/green]\n\n"
                 f"Created {result.entities} entities\n"
-                f"Added {result.relations} relations",
+                f"Added {result.relations} relations\n"
+                f"Skipped {result.skipped_entities} entities\n",
                 expand=False,
             )
         )
 
-        console.print("\nRun 'basic-memory sync' to index the new files.")
-
     except Exception as e:
         logger.error("Import failed")
         typer.echo(f"Error during import: {e}", err=True)

src/basic_memory/cli/commands/mcp.py

@@ -1,11 +1,13 @@
 """MCP server command with streamable HTTP transport."""
 
-import asyncio
+import os
 import typer
+from typing import Optional
 
 from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager, init_mcp_logging
 
-# Import mcp instance
+# Import mcp instance (has lifespan that handles initialization and file sync)
 from basic_memory.mcp.server import mcp as mcp_server  # pragma: no cover
 
 # Import mcp tools to register them
@@ -15,75 +17,60 @@ import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
 import basic_memory.mcp.prompts  # noqa: F401  # pragma: no cover
 from loguru import logger
 
+config = ConfigManager().config
 
-@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"),
-):  # pragma: no cover
-    """Run the MCP server with configurable transport options.
+if not config.cloud_mode_enabled:
 
-    This command starts an MCP server using one of three transport options:
+    @app.command()
+    def mcp(
+        transport: str = typer.Option(
+            "stdio", help="Transport type: stdio, streamable-http, or sse"
+        ),
+        host: str = typer.Option(
+            "0.0.0.0", help="Host for HTTP transports (use 0.0.0.0 to allow external connections)"
+        ),
+        port: int = typer.Option(8000, help="Port for HTTP transports"),
+        path: str = typer.Option("/mcp", help="Path prefix for streamable-http transport"),
+        project: Optional[str] = typer.Option(None, help="Restrict MCP server to single project"),
+    ):  # pragma: no cover
+        """Run the MCP server with configurable transport options.
 
-    - stdio: Standard I/O (good for local usage)
-    - streamable-http: Recommended for web deployments (default)
-    - sse: Server-Sent Events (for compatibility with existing clients)
-    """
+        This command starts an MCP server using one of three transport options:
 
-    # Check if OAuth is enabled
-    import os
+        - stdio: Standard I/O (good for local usage)
+        - streamable-http: Recommended for web deployments (default)
+        - sse: Server-Sent Events (for compatibility with existing clients)
 
-    auth_enabled = os.getenv("FASTMCP_AUTH_ENABLED", "false").lower() == "true"
-    if auth_enabled:
-        logger.info("OAuth authentication is ENABLED")
-        logger.info(f"Issuer URL: {os.getenv('FASTMCP_AUTH_ISSUER_URL', 'http://localhost:8000')}")
-        if os.getenv("FASTMCP_AUTH_REQUIRED_SCOPES"):
-            logger.info(f"Required scopes: {os.getenv('FASTMCP_AUTH_REQUIRED_SCOPES')}")
-    else:
-        logger.info("OAuth authentication is DISABLED")
+        Initialization, file sync, and cleanup are handled by the MCP server's lifespan.
+        """
+        # Initialize logging for MCP (file only, stdout breaks protocol)
+        init_mcp_logging()
 
-    from basic_memory.config import app_config
-    from basic_memory.services.initialization import initialize_file_sync
+        # 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)
 
-    # Start the MCP server with the specified transport
+            # 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
+        # Run the MCP server (blocks)
+        # Lifespan handles: initialization, migrations, file sync, cleanup
+        logger.info(f"Starting MCP server with {transport.upper()} transport")
 
-    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")
-
-    # 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",
+            )

src/basic_memory/cli/commands/project.py

@@ -1,6 +1,5 @@
 """Command module for basic-memory project management."""
 
-import asyncio
 import os
 from pathlib import Path
 
@@ -9,21 +8,27 @@ from rich.console import Console
 from rich.table import Table
 
 from basic_memory.cli.app import app
-from basic_memory.mcp.project_session import session
-from basic_memory.mcp.resources.project_info import project_info
+from basic_memory.cli.commands.command_utils import get_project_info, run_with_cleanup
+from basic_memory.config import ConfigManager
 import json
 from datetime import datetime
 
 from rich.panel import Panel
-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
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.tools.utils import call_get, call_post, call_delete, call_put, call_patch
+from basic_memory.schemas.project_info import ProjectList, ProjectStatusResponse
+from basic_memory.utils import generate_permalink, normalize_project_path
+
+# 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()
 
@@ -42,22 +47,50 @@ def format_path(path: str) -> str:
 
 @project_app.command("list")
 def list_projects() -> None:
-    """List all configured projects."""
-    # Use API to list projects
+    """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())
+
     try:
-        response = asyncio.run(call_get(client, "/projects/projects"))
-        result = ProjectList.model_validate(response.json())
+        result = run_with_cleanup(_list_projects())
+        config = ConfigManager().config
 
         table = Table(title="Basic Memory Projects")
         table.add_column("Name", style="cyan")
         table.add_column("Path", style="green")
-        table.add_column("Default", style="yellow")
-        table.add_column("Active", style="magenta")
+
+        # 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")
 
         for project in result.projects:
-            is_default = "✓" if project.is_default else ""
-            is_active = "✓" if session.get_current_project() == project.name else ""
-            table.add_row(project.name, format_path(project.path), is_default, is_active)
+            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)
 
         console.print(table)
     except Exception as e:
@@ -68,115 +101,708 @@ def list_projects() -> None:
 @project_app.command("add")
 def add_project(
     name: str = typer.Argument(..., help="Name of the project"),
-    path: str = typer.Argument(..., help="Path to the project directory"),
+    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)"
+    ),
     set_default: bool = typer.Option(False, "--default", help="Set as default project"),
 ) -> None:
-    """Add a new project."""
-    # Resolve to absolute path
-    resolved_path = os.path.abspath(os.path.expanduser(path))
+    """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())
 
     try:
-        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())
-
+        result = run_with_cleanup(_add_project())
         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)
 
-    # 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("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
+        run_with_cleanup(_verify_project_exists())
+
+        # Resolve and create local path
+        resolved_path = Path(os.path.abspath(os.path.expanduser(local_path)))
+        resolved_path.mkdir(parents=True, exist_ok=True)
+
+        # Update 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)
 
 
 @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 from configuration."""
-    try:
-        project_name = generate_permalink(name)
-        response = asyncio.run(call_delete(client, f"/projects/{project_name}"))
-        result = ProjectStatusResponse.model_validate(response.json())
+    """Remove a project."""
 
+    async def _remove_project():
+        async with get_client() as client:
+            # Convert name to permalink for efficient resolution
+            project_permalink = generate_permalink(name)
+
+            # Use v2 project resolver to find project ID by permalink
+            resolve_data = {"identifier": project_permalink}
+            response = await call_post(client, "/v2/projects/resolve", json=resolve_data)
+            target_project = response.json()
+
+            # Use v2 API with project ID
+            response = await call_delete(
+                client, f"/v2/projects/{target_project['external_id']}?delete_notes={delete_notes}"
+            )
+            return ProjectStatusResponse.model_validate(response.json())
+
+    try:
+        # Get config to check for local sync path and bisync state
+        config = ConfigManager().config
+        local_path = None
+        has_bisync_state = False
+
+        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 = run_with_cleanup(_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 default"),
+    name: str = typer.Argument(..., help="Name of the project to set as CLI default"),
 ) -> None:
-    """Set the default project and activate it for the current session."""
+    """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:
+            # Convert name to permalink for efficient resolution
+            project_permalink = generate_permalink(name)
+
+            # Use v2 project resolver to find project ID by permalink
+            resolve_data = {"identifier": project_permalink}
+            response = await call_post(client, "/v2/projects/resolve", json=resolve_data)
+            target_project = response.json()
+
+            # Use v2 API with project ID
+            response = await call_put(
+                client, f"/v2/projects/{target_project['external_id']}/default"
+            )
+            return ProjectStatusResponse.model_validate(response.json())
+
     try:
-        project_name = generate_permalink(name)
-
-        response = asyncio.run(call_put(client, f"/projects/{project_name}/default"))
-        result = ProjectStatusResponse.model_validate(response.json())
-
+        result = run_with_cleanup(_set_default())
         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 should have updated both config and MCP session
-    # No need for manual reload - the project service handles this automatically
-    console.print("[green]Project activated for current session[/green]")
-
 
 @project_app.command("sync-config")
 def synchronize_projects() -> None:
-    """Synchronize project config between configuration file and database."""
-    # Call the API to synchronize projects
+    """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())
 
     try:
-        response = asyncio.run(call_post(client, "/projects/sync"))
-        result = ProjectStatusResponse.model_validate(response.json())
-
+        result = run_with_cleanup(_sync_config())
         console.print(f"[green]{result.message}[/green]")
     except Exception as e:  # pragma: no cover
         console.print(f"[red]Error synchronizing projects: {str(e)}[/red]")
         raise typer.Exit(1)
 
 
+@project_app.command("move")
+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)
+
+    # 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 = run_with_cleanup(_move_project())
+        console.print(f"[green]{result.message}[/green]")
+
+        # Show important file movement reminder
+        console.print()  # Empty line for spacing
+        console.print(
+            Panel(
+                "[bold red]IMPORTANT:[/bold red] Project configuration updated successfully.\n\n"
+                "[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",
+                border_style="yellow",
+                expand=False,
+            )
+        )
+
+    except Exception as e:
+        console.print(f"[red]Error moving project: {str(e)}[/red]")
+        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 = run_with_cleanup(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 = run_with_cleanup(_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 = run_with_cleanup(_trigger_db_sync())
+                    console.print(f"[dim]Database sync initiated: {result.get('message')}[/dim]")
+                except Exception as e:
+                    console.print(f"[yellow]Warning: Could not trigger database sync: {e}[/yellow]")
+        else:
+            console.print(f"[red]{name} sync failed[/red]")
+            raise typer.Exit(1)
+
+    except RcloneError as e:
+        console.print(f"[red]Sync error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@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 = run_with_cleanup(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 = run_with_cleanup(_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 = run_with_cleanup(_trigger_db_sync())
+                    console.print(f"[dim]Database sync initiated: {result.get('message')}[/dim]")
+                except Exception as e:
+                    console.print(f"[yellow]Warning: Could not trigger database sync: {e}[/yellow]")
+        else:
+            console.print(f"[red]{name} bisync failed[/red]")
+            raise typer.Exit(1)
+
+    except RcloneError as e:
+        console.print(f"[red]Bisync error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@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 = run_with_cleanup(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 = run_with_cleanup(_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 = run_with_cleanup(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 = run_with_cleanup(_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(project_info.fn())  # type: ignore  # pyright: ignore [reportAttributeAccessIssue]
+        info = run_with_cleanup(get_project_info(name))
 
         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")
 
@@ -192,7 +818,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")
 
@@ -203,7 +829,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")
@@ -217,7 +843,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")
@@ -236,44 +862,8 @@ 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")
@@ -281,7 +871,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, "✓" if is_default else "")
+                projects_table.add_row(name, project_path, "[X]" if is_default else "")
 
             console.print(projects_table)
 

src/basic_memory/cli/commands/status.py

@@ -1,20 +1,20 @@
 """Status command for basic-memory CLI."""
 
-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.cli.commands.sync import get_sync_service
-from basic_memory.config import config, app_config
-from basic_memory.repository import ProjectRepository
-from basic_memory.sync.sync_service import SyncReport
+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
 
 # Create rich console
 console = Console()
@@ -47,7 +47,7 @@ def add_files_to_tree(
                 branch.add(f"[{style}]{file_name}[/{style}]")
 
 
-def group_changes_by_directory(changes: SyncReport) -> Dict[str, Dict[str, int]]:
+def group_changes_by_directory(changes: SyncReportResponse) -> Dict[str, Dict[str, int]]:
     """Group changes by directory for summary view."""
     by_dir = {}
     for change_type, paths in [
@@ -87,11 +87,13 @@ def build_directory_summary(counts: Dict[str, int]) -> str:
     return " ".join(parts)
 
 
-def display_changes(project_name: str, title: str, changes: SyncReport, verbose: bool = False):
+def display_changes(
+    project_name: str, title: str, changes: SyncReportResponse, verbose: bool = False
+):
     """Display changes using Rich for better visualization."""
     tree = Tree(f"{project_name}: {title}")
 
-    if changes.total == 0:
+    if changes.total == 0 and not changes.skipped_files:
         tree.add("No changes")
         console.print(Panel(tree, expand=False))
         return
@@ -111,6 +113,13 @@ def display_changes(project_name: str, title: str, changes: SyncReport, verbose:
         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)
@@ -119,33 +128,46 @@ def display_changes(project_name: str, title: str, changes: SyncReport, verbose:
             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(verbose: bool = False):  # pragma: no cover
+async def run_status(project: Optional[str] = None, verbose: bool = False):  # pragma: no cover
     """Check sync status of files vs database."""
-    # Check knowledge/ directory
 
-    _, 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")
+    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())
 
-    sync_service = await get_sync_service(project)
-    knowledge_changes = await sync_service.scan(config.home)
-    display_changes(project.name, "Status", knowledge_changes, verbose)
+            display_changes(project_item.name, "Status", sync_report, verbose)
+
+    except (ValueError, ToolError) as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
 
 
 @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."""
+    from basic_memory.cli.commands.command_utils import run_with_cleanup
+
     try:
-        asyncio.run(run_status(verbose))  # pragma: no cover
+        run_with_cleanup(run_status(project, verbose))  # pragma: no cover
     except Exception as e:
         logger.error(f"Error checking status: {e}")
         typer.echo(f"Error checking status: {e}", err=True)

src/basic_memory/cli/commands/sync.py

@@ -1,234 +0,0 @@
-"""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 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
-from basic_memory.config import app_config
-
-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."""
-    _, 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."""
-    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."""
-    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."""
-    _, 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."""
-    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

src/basic_memory/cli/commands/tool.py

@@ -1,6 +1,5 @@
 """CLI tool commands for Basic Memory."""
 
-import asyncio
 import sys
 from typing import Annotated, List, Optional
 
@@ -9,6 +8,8 @@ from loguru import logger
 from rich import print as rprint
 
 from basic_memory.cli.app import app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.config import ConfigManager
 
 # Import prompts
 from basic_memory.mcp.prompts.continue_conversation import (
@@ -34,6 +35,12 @@ app.add_typer(tool_app, name="tool", help="Access to MCP tools via CLI")
 def write_note(
     title: Annotated[str, typer.Option(help="The title of the note")],
     folder: Annotated[str, typer.Option(help="The folder to create the note in")],
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to write to. If not provided, the default project will be used."
+        ),
+    ] = None,
     content: Annotated[
         Optional[str],
         typer.Option(
@@ -90,7 +97,19 @@ def write_note(
             typer.echo("Empty content provided. Please provide non-empty content.", err=True)
             raise typer.Exit(1)
 
-        note = asyncio.run(mcp_write_note.fn(title, content, folder, tags))
+        # look for the project in the config
+        config_manager = ConfigManager()
+        project_name = None
+        if project is not None:
+            project_name, _ = config_manager.get_project(project)
+            if not project_name:
+                typer.echo(f"No project found named: {project}", err=True)
+                raise typer.Exit(1)
+
+        # use the project name, or the default from the config
+        project_name = project_name or config_manager.default_project
+
+        note = run_with_cleanup(mcp_write_note.fn(title, content, folder, project_name, tags))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -100,10 +119,33 @@ def write_note(
 
 
 @tool_app.command()
-def read_note(identifier: str, page: int = 1, page_size: int = 10):
+def read_note(
+    identifier: str,
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to use for the note. If not provided, the default project will be used."
+        ),
+    ] = None,
+    page: int = 1,
+    page_size: int = 10,
+):
     """Read a markdown note from the knowledge base."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
     try:
-        note = asyncio.run(mcp_read_note.fn(identifier, page, page_size))
+        note = run_with_cleanup(mcp_read_note.fn(identifier, project_name, page, page_size))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -115,6 +157,10 @@ def read_note(identifier: str, page: int = 1, page_size: int = 10):
 @tool_app.command()
 def build_context(
     url: MemoryUrl,
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
+    ] = None,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
     page: int = 1,
@@ -122,9 +168,23 @@ def build_context(
     max_related: int = 10,
 ):
     """Get context needed to continue a discussion."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
     try:
-        context = asyncio.run(
+        context = run_with_cleanup(
             mcp_build_context.fn(
+                project=project_name,
                 url=url,
                 depth=depth,
                 timeframe=timeframe,
@@ -150,30 +210,21 @@ def recent_activity(
     type: Annotated[Optional[List[SearchItemType]], typer.Option()] = None,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
 ):
     """Get recent activity across the knowledge base."""
     try:
-        context = asyncio.run(
+        result = run_with_cleanup(
             mcp_recent_activity.fn(
                 type=type,  # pyright: ignore [reportArgumentType]
                 depth=depth,
                 timeframe=timeframe,
-                page=page,
-                page_size=page_size,
-                max_related=max_related,
             )
         )
-        # Use json module for more controlled serialization
-        import json
-
-        context_dict = context.model_dump(exclude_none=True)
-        print(json.dumps(context_dict, indent=2, ensure_ascii=True, default=str))
+        # The tool now returns a formatted string directly
+        print(result)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
-            typer.echo(f"Error during build_context: {e}", err=True)
+            typer.echo(f"Error during recent_activity: {e}", err=True)
             raise typer.Exit(1)
         raise
 
@@ -183,6 +234,12 @@ def search_notes(
     query: str,
     permalink: Annotated[bool, typer.Option("--permalink", help="Search permalink values")] = False,
     title: Annotated[bool, typer.Option("--title", help="Search title values")] = False,
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to use for the note. If not provided, the default project will be used."
+        ),
+    ] = None,
     after_date: Annotated[
         Optional[str],
         typer.Option("--after_date", help="Search results after date, eg. '2d', '1 week'"),
@@ -191,6 +248,19 @@ def search_notes(
     page_size: int = 10,
 ):
     """Search across all content in the knowledge base."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
     if permalink and title:  # pragma: no cover
         print("Cannot search both permalink and title")
         raise typer.Abort()
@@ -209,9 +279,10 @@ def search_notes(
         search_type = ("title" if title else None,)
         search_type = "text" if search_type is None else search_type
 
-        results = asyncio.run(
+        results = run_with_cleanup(
             mcp_search.fn(
                 query,
+                project_name,
                 search_type=search_type,
                 page=page,
                 after_date=after_date,
@@ -241,7 +312,7 @@ def continue_conversation(
     """Prompt to continue a previous conversation or work session."""
     try:
         # Prompt functions return formatted strings directly
-        session = asyncio.run(mcp_continue_conversation.fn(topic=topic, timeframe=timeframe))  # type: ignore
+        session = run_with_cleanup(mcp_continue_conversation.fn(topic=topic, timeframe=timeframe))  # type: ignore
         rprint(session)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):

src/basic_memory/cli/container.py

@@ -0,0 +1,84 @@
+"""CLI composition root for Basic Memory.
+
+This container owns reading ConfigManager and environment variables for the
+CLI entrypoint. Downstream modules receive config/dependencies explicitly
+rather than reading globals.
+
+Design principles:
+- Only this module reads ConfigManager directly
+- Runtime mode (cloud/local/test) is resolved here
+- Different CLI commands may need different initialization
+"""
+
+from dataclasses import dataclass
+
+from basic_memory.config import BasicMemoryConfig, ConfigManager
+from basic_memory.runtime import RuntimeMode, resolve_runtime_mode
+
+
+@dataclass
+class CliContainer:
+    """Composition root for the CLI entrypoint.
+
+    Holds resolved configuration and runtime context.
+    Created once at CLI startup, then used by subcommands.
+    """
+
+    config: BasicMemoryConfig
+    mode: RuntimeMode
+
+    @classmethod
+    def create(cls) -> "CliContainer":
+        """Create container by reading ConfigManager.
+
+        This is the single point where CLI reads global config.
+        """
+        config = ConfigManager().config
+        mode = resolve_runtime_mode(
+            cloud_mode_enabled=config.cloud_mode_enabled,
+            is_test_env=config.is_test_env,
+        )
+        return cls(config=config, mode=mode)
+
+    # --- Runtime Mode Properties ---
+
+    @property
+    def is_cloud_mode(self) -> bool:
+        """Whether running in cloud mode."""
+        return self.mode.is_cloud
+
+
+# Module-level container instance (set by app callback)
+_container: CliContainer | None = None
+
+
+def get_container() -> CliContainer:
+    """Get the current CLI container.
+
+    Returns:
+        The CLI container
+
+    Raises:
+        RuntimeError: If container hasn't been initialized
+    """
+    if _container is None:
+        raise RuntimeError("CLI container not initialized. Call set_container() first.")
+    return _container
+
+
+def set_container(container: CliContainer) -> None:
+    """Set the CLI container (called by app callback)."""
+    global _container
+    _container = container
+
+
+def get_or_create_container() -> CliContainer:
+    """Get existing container or create new one.
+
+    This is useful for CLI commands that might be called before
+    the main app callback runs (e.g., eager options).
+    """
+    global _container
+    if _container is None:
+        _container = CliContainer.create()
+    return _container

src/basic_memory/cli/main.py

@@ -4,7 +4,7 @@ from basic_memory.cli.app import app  # pragma: no cover
 
 # Register commands
 from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
-    auth,
+    cloud,
     db,
     import_chatgpt,
     import_claude_conversations,
@@ -13,10 +13,15 @@ from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
     mcp,
     project,
     status,
-    sync,
     tool,
 )
 
+# Re-apply warning filter AFTER all imports
+# (authlib adds a DeprecationWarning filter that overrides ours)
+import warnings  # pragma: no cover
+
+warnings.filterwarnings("ignore")  # pragma: no cover
+
 if __name__ == "__main__":  # pragma: no cover
     # start the app
     app()

src/basic_memory/config.py

@@ -3,14 +3,15 @@
 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 Field, field_validator
+from pydantic import BaseModel, Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-import basic_memory
 from basic_memory.utils import setup_logging, generate_permalink
 
 
@@ -23,6 +24,13 @@ 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."""
@@ -32,13 +40,29 @@ class ProjectConfig:
 
     @property
     def project(self):
-        return self.name
+        return self.name  # pragma: no cover
 
     @property
     def project_url(self) -> str:  # pragma: no cover
         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."""
 
@@ -47,22 +71,62 @@ 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 {},
         description="Mapping of project names to their filesystem paths",
     )
     default_project: str = Field(
         default="main",
         description="Name of the default project to use",
     )
+    default_project_mode: bool = Field(
+        default=False,
+        description="When True, MCP tools automatically use default_project when no project parameter is specified. Enables simplified UX for single-project workflows.",
+    )
 
     # 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.",
+    )
+
+    # Database connection pool configuration (Postgres only)
+    db_pool_size: int = Field(
+        default=20,
+        description="Number of connections to keep in the pool (Postgres only)",
+        gt=0,
+    )
+    db_pool_overflow: int = Field(
+        default=40,
+        description="Max additional connections beyond pool_size under load (Postgres only)",
+        gt=0,
+    )
+    db_pool_recycle: int = Field(
+        default=180,
+        description="Recycle connections after N seconds to prevent stale connections. Default 180s works well with Neon's ~5 minute scale-to-zero (Postgres only)",
+        gt=0,
+    )
+
     # Watch service configuration
     sync_delay: int = Field(
         default=1000, description="Milliseconds to wait after changes before syncing", gt=0
     )
 
+    watch_project_reload_interval: int = Field(
+        default=300,
+        description="Seconds between reloading project list in watch service. Higher values reduce CPU usage by minimizing watcher restarts. Default 300s (5 min) balances efficiency with responsiveness to new projects.",
+        gt=0,
+    )
+
     # update permalinks on move
     update_permalinks_on_move: bool = Field(
         default=False,
@@ -74,11 +138,155 @@ 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,
+    )
+
+    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.",
+    )
+
+    # File formatting configuration
+    format_on_save: bool = Field(
+        default=False,
+        description="Automatically format files after saving using configured formatter. Disabled by default.",
+    )
+
+    formatter_command: Optional[str] = Field(
+        default=None,
+        description="External formatter command. Use {file} as placeholder for file path. If not set, uses built-in mdformat (Python, no Node.js required). Set to 'npx prettier --write {file}' for Prettier.",
+    )
+
+    formatters: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Per-extension formatters. Keys are extensions (without dot), values are commands. Example: {'md': 'prettier --write {file}', 'json': 'prettier --write {file}'}",
+    )
+
+    formatter_timeout: float = Field(
+        default=5.0,
+        description="Maximum seconds to wait for formatter to complete",
+        gt=0,
+    )
+
+    # Project path constraints
+    project_root: 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).",
+    )
+
+    # Cloud configuration
+    cloud_client_id: str = Field(
+        default="client_01K6KWQPW6J1M8VV7R3TZP5A6M",
+        description="OAuth client ID for Basic Memory Cloud",
+    )
+
+    cloud_domain: str = Field(
+        default="https://eloquent-lotus-05.authkit.app",
+        description="AuthKit domain for Basic Memory Cloud",
+    )
+
+    cloud_host: str = Field(
+        default_factory=lambda: os.getenv(
+            "BASIC_MEMORY_CLOUD_HOST", "https://cloud.basicmemory.com"
+        ),
+        description="Basic Memory Cloud 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 is_test_env(self) -> bool:
+        """Check if running in a test environment.
+
+        Returns True if any of:
+        - env field is set to "test"
+        - BASIC_MEMORY_ENV environment variable is "test"
+        - PYTEST_CURRENT_TEST environment variable is set (pytest is running)
+
+        Used to disable features like file watchers during tests.
+        """
+        return (
+            self.env == "test"
+            or os.getenv("BASIC_MEMORY_ENV", "").lower() == "test"
+            or os.getenv("PYTEST_CURRENT_TEST") is not None
+        )
+
+    @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
+
+    @classmethod
+    def for_cloud_tenant(
+        cls,
+        database_url: str,
+        projects: Optional[Dict[str, str]] = None,
+    ) -> "BasicMemoryConfig":
+        """Create config for cloud tenant - no config.json, database is source of truth.
+
+        This factory method creates a BasicMemoryConfig suitable for cloud deployments
+        where:
+        - Database is Postgres (Neon), not SQLite
+        - Projects are discovered from the database, not config file
+        - Path validation is skipped (no local filesystem in cloud)
+        - Initialization sync is skipped (stateless deployment)
+
+        Args:
+            database_url: Postgres connection URL for tenant database
+            projects: Optional project mapping (usually empty, discovered from DB)
+
+        Returns:
+            BasicMemoryConfig configured for cloud mode
+        """
+        return cls(  # pragma: no cover
+            database_backend=DatabaseBackend.POSTGRES,
+            database_url=database_url,
+            projects=projects or {},
+            cloud_mode=True,
+            skip_initialization_sync=True,
+        )
+
     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
@@ -92,15 +300,20 @@ class BasicMemoryConfig(BaseSettings):
 
     def model_post_init(self, __context: Any) -> None:
         """Ensure configuration is valid after initialization."""
-        # Ensure main project exists
-        if "main" not in self.projects:  # pragma: no cover
+        # Skip project initialization in cloud mode - projects are discovered from DB
+        if self.database_backend == DatabaseBackend.POSTGRES:  # pragma: no cover
+            return  # pragma: no cover
+
+        # Ensure at least one project exists; if none exist then create main
+        if not self.projects:  # pragma: no cover
             self.projects["main"] = str(
                 Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory"))
             )
 
-        # Ensure default project is valid
+        # Ensure default project is valid (i.e. points to an existing project)
         if self.default_project not in self.projects:  # pragma: no cover
-            self.default_project = "main"
+            # Set default to first available project
+            self.default_project = next(iter(self.projects.keys()))
 
     @property
     def app_database_path(self) -> Path:
@@ -124,6 +337,7 @@ class BasicMemoryConfig(BaseSettings):
         """
 
         # Load the app-level database path from the global config
+        config_manager = ConfigManager()
         config = config_manager.load_config()  # pragma: no cover
         return config.app_database_path  # pragma: no cover
 
@@ -132,19 +346,34 @@ class BasicMemoryConfig(BaseSettings):
         """Get all configured projects as ProjectConfig objects."""
         return [ProjectConfig(name=name, home=Path(path)) for name, path in self.projects.items()]
 
-    @field_validator("projects")
-    @classmethod
-    def ensure_project_paths_exists(cls, v: Dict[str, str]) -> Dict[str, str]:  # pragma: no cover
-        """Ensure project path exists."""
-        for name, path_value in v.items():
+    @model_validator(mode="after")
+    def ensure_project_paths_exists(self) -> "BasicMemoryConfig":  # pragma: no cover
+        """Ensure project paths exist.
+
+        Skips path creation when using Postgres backend (cloud mode) since
+        cloud tenants don't use local filesystem paths.
+        """
+        # Skip path creation for cloud mode - no local filesystem
+        if self.database_backend == DatabaseBackend.POSTGRES:
+            return self
+
+        for name, path_value in self.projects.items():
             path = Path(path_value)
-            if not Path(path).exists():
+            if not path.exists():
                 try:
                     path.mkdir(parents=True)
                 except Exception as e:
                     logger.error(f"Failed to create project path: {e}")
                     raise e
-        return v
+        return self
+
+    @property
+    def data_dir_path(self):
+        return Path.home() / DATA_DIR_NAME
+
+
+# Module-level cache for configuration
+_CONFIG_CACHE: Optional[BasicMemoryConfig] = None
 
 
 class ConfigManager:
@@ -156,37 +385,76 @@ class ConfigManager:
         if isinstance(home, str):
             home = Path(home)
 
-        self.config_dir = home / DATA_DIR_NAME
+        # 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)
 
-        # Load or create configuration
-        self.config = self.load_config()
+    @property
+    def config(self) -> BasicMemoryConfig:
+        """Get configuration, loading it lazily if needed."""
+        return self.load_config()
 
     def load_config(self) -> BasicMemoryConfig:
-        """Load configuration from file or create default."""
+        """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
+
         if self.config_file.exists():
             try:
-                data = json.loads(self.config_file.read_text(encoding="utf-8"))
-                return BasicMemoryConfig(**data)
+                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
             except Exception as e:  # pragma: no cover
-                logger.error(f"Failed to load config: {e}")
-                config = BasicMemoryConfig()
-                self.save_config(config)
-                return config
+                logger.exception(f"Failed to load config: {e}")
+                raise e
         else:
             config = BasicMemoryConfig()
             self.save_config(config)
             return config
 
     def save_config(self, config: BasicMemoryConfig) -> None:
-        """Save configuration to file."""
-        try:
-            self.config_file.write_text(json.dumps(config.model_dump(), indent=2))
-        except Exception as e:  # pragma: no cover
-            logger.error(f"Failed to save config: {e}")
+        """Save configuration to file and invalidate cache."""
+        global _CONFIG_CACHE
+        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]:
@@ -208,8 +476,10 @@ class ConfigManager:
         project_path = Path(path)
         project_path.mkdir(parents=True, exist_ok=True)  # pragma: no cover
 
-        self.config.projects[name] = str(project_path)
-        self.save_config(self.config)
+        # Load config, modify it, and save it
+        config = self.load_config()
+        config.projects[name] = str(project_path)
+        self.save_config(config)
         return ProjectConfig(name=name, home=project_path)
 
     def remove_project(self, name: str) -> None:
@@ -219,11 +489,14 @@ class ConfigManager:
         if not project_name:  # pragma: no cover
             raise ValueError(f"Project '{name}' not found")
 
-        if project_name == self.config.default_project:  # pragma: no cover
+        # Load config, check, modify, and save
+        config = self.load_config()
+        if project_name == config.default_project:  # pragma: no cover
             raise ValueError(f"Cannot remove the default project '{name}'")
 
-        del self.config.projects[name]
-        self.save_config(self.config)
+        # Use the found project_name (which may differ from input name due to permalink matching)
+        del config.projects[project_name]
+        self.save_config(config)
 
     def set_default_project(self, name: str) -> None:
         """Set the default project."""
@@ -231,15 +504,18 @@ class ConfigManager:
         if not project_name:  # pragma: no cover
             raise ValueError(f"Project '{name}' not found")
 
-        self.config.default_project = name
-        self.save_config(self.config)
+        # Load config, modify, and save
+        config = self.load_config()
+        config.default_project = project_name
+        self.save_config(config)
 
     def get_project(self, name: str) -> Tuple[str, str] | Tuple[None, None]:
         """Look up a project from the configuration by name or permalink"""
         project_permalink = generate_permalink(name)
-        for name, path in app_config.projects.items():
-            if project_permalink == generate_permalink(name):
-                return name, path
+        app_config = self.config
+        for project_name, path in app_config.projects.items():
+            if project_permalink == generate_permalink(project_name):
+                return project_name, path
         return None, None
 
 
@@ -252,14 +528,14 @@ def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
     actual_project_name = None
 
     # load the config from file
-    global app_config
+    config_manager = ConfigManager()
     app_config = config_manager.load_config()
 
     # Get project name from environment variable
     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. Use the --project flag or set the default project in the config instead. Setting default project to {os_project_name}"
+            f"BASIC_MEMORY_PROJECT is not supported anymore. 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
@@ -282,76 +558,48 @@ def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
     raise ValueError(f"Project '{actual_project_name}' not found")  # pragma: no cover
 
 
-# Create config manager
-config_manager = ConfigManager()
-
-# Export the app-level config
-app_config: BasicMemoryConfig = config_manager.config
-
-# Load project config for the default project (backward compatibility)
-config: ProjectConfig = get_project_config()
+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))
+    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.
+# Logging initialization functions for different entry points
 
-    This is used by the CLI when --project flag is specified.
+
+def init_cli_logging() -> None:  # pragma: no cover
+    """Initialize logging for CLI commands - file only.
+
+    CLI commands should not log to stdout to avoid interfering with
+    command output and shell integration.
     """
-    global config
-    config = get_project_config(project_name)  # pragma: no cover
+    log_level = os.getenv("BASIC_MEMORY_LOG_LEVEL", "INFO")
+    setup_logging(log_level=log_level, log_to_file=True)
 
 
-# setup logging to a single log file in user home directory
-user_home = Path.home()
-log_dir = user_home / DATA_DIR_NAME
-log_dir.mkdir(parents=True, exist_ok=True)
+def init_mcp_logging() -> None:  # pragma: no cover
+    """Initialize logging for MCP server - file only.
 
-
-# Process info for logging
-def get_process_name():  # pragma: no cover
+    MCP server must not log to stdout as it would corrupt the
+    JSON-RPC protocol communication.
     """
-    get the type of process for logging
-    """
-    import sys
+    log_level = os.getenv("BASIC_MEMORY_LOG_LEVEL", "INFO")
+    setup_logging(log_level=log_level, log_to_file=True)
 
-    if "sync" in sys.argv:
-        return "sync"
-    elif "mcp" in sys.argv:
-        return "mcp"
-    elif "cli" in sys.argv:
-        return "cli"
+
+def init_api_logging() -> None:  # pragma: no cover
+    """Initialize logging for API server.
+
+    Cloud mode (BASIC_MEMORY_CLOUD_MODE=1): stdout with structured context
+    Local mode: file only
+    """
+    log_level = os.getenv("BASIC_MEMORY_LOG_LEVEL", "INFO")
+    cloud_mode = os.getenv("BASIC_MEMORY_CLOUD_MODE", "").lower() in ("1", "true")
+    if cloud_mode:
+        setup_logging(log_level=log_level, log_to_stdout=True, structured_context=True)
     else:
-        return "api"
-
-
-process_name = get_process_name()
-
-# Global flag to track if logging has been set up
-_LOGGING_SETUP = False
-
-
-# Logging
-
-
-def setup_basic_memory_logging():  # pragma: no cover
-    """Set up logging for basic-memory, ensuring it only happens once."""
-    global _LOGGING_SETUP
-    if _LOGGING_SETUP:
-        # We can't log before logging is set up
-        # print("Skipping duplicate logging setup")
-        return
-
-    setup_logging(
-        env=config_manager.config.env,
-        home_dir=user_home,  # Use user home for logs
-        log_level=config_manager.load_config().log_level,
-        log_file=f"{DATA_DIR_NAME}/basic-memory-{process_name}.log",
-        console=False,
-    )
-
-    logger.info(f"Basic Memory {basic_memory.__version__} (Project: {config.project})")
-    _LOGGING_SETUP = True
-
-
-# Set up logging
-setup_basic_memory_logging()
+        setup_logging(log_level=log_level, log_to_file=True)

src/basic_memory/db.py

@@ -1,15 +1,17 @@
 import asyncio
+import os
+import sys
 from contextlib import asynccontextmanager
 from enum import Enum, auto
 from pathlib import Path
 from typing import AsyncGenerator, Optional
 
-from basic_memory.config import BasicMemoryConfig
+from basic_memory.config import BasicMemoryConfig, ConfigManager, DatabaseBackend
 from alembic import command
 from alembic.config import Config
 
 from loguru import logger
-from sqlalchemy import text
+from sqlalchemy import text, event
 from sqlalchemy.ext.asyncio import (
     create_async_engine,
     async_sessionmaker,
@@ -17,13 +19,29 @@ from sqlalchemy.ext.asyncio import (
     AsyncEngine,
     async_scoped_session,
 )
+from sqlalchemy.pool import NullPool
 
-from basic_memory.repository.search_repository import SearchRepository
+from basic_memory.repository.postgres_search_repository import PostgresSearchRepository
+from basic_memory.repository.sqlite_search_repository import SQLiteSearchRepository
+
+# -----------------------------------------------------------------------------
+# Windows event loop policy
+# -----------------------------------------------------------------------------
+# On Windows, the default ProactorEventLoop has known rough edges with aiosqlite
+# during shutdown/teardown (threads posting results to a loop that's closing),
+# which can manifest as:
+# - "RuntimeError: Event loop is closed"
+# - "IndexError: pop from an empty deque"
+#
+# The SelectorEventLoop doesn't support subprocess operations, so code that uses
+# asyncio.create_subprocess_shell() (like sync_service._quick_count_files) must
+# detect Windows and use fallback implementations.
+if sys.platform == "win32":  # pragma: no cover
+    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
 
 # Module level state
 _engine: Optional[AsyncEngine] = None
 _session_maker: Optional[async_sessionmaker[AsyncSession]] = None
-_migrations_completed: bool = False
 
 
 class DatabaseType(Enum):
@@ -31,10 +49,41 @@ class DatabaseType(Enum):
 
     MEMORY = auto()
     FILESYSTEM = auto()
+    POSTGRES = auto()
 
     @classmethod
-    def get_db_url(cls, db_path: Path, db_type: "DatabaseType") -> str:
-        """Get SQLAlchemy URL for database path."""
+    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, FILESYSTEM, or POSTGRES)
+            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
+
+        # Handle explicit Postgres type
+        if db_type == cls.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}")
+            return config.database_url
+
+        # Check if Postgres backend is configured (for backward compatibility)
+        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}")
+            return config.database_url
+
+        # SQLite databases
         if db_type == cls.MEMORY:
             logger.info("Using in-memory SQLite database")
             return "sqlite+aiosqlite://"
@@ -62,7 +111,14 @@ async def scoped_session(
     factory = get_scoped_session_factory(session_maker)
     session = factory()
     try:
-        await session.execute(text("PRAGMA foreign_keys=ON"))
+        # 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"))
+
         yield session
         await session.commit()
     except Exception:
@@ -73,13 +129,147 @@ 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, config: BasicMemoryConfig) -> AsyncEngine:
+    """Create Postgres async engine with appropriate configuration.
+
+    Args:
+        db_url: Postgres connection URL (postgresql+asyncpg://...)
+        config: BasicMemoryConfig with pool settings
+
+    Returns:
+        Configured async engine for Postgres
+    """
+    # Use NullPool connection issues.
+    # Assume connection pooler like PgBouncer handles connection pooling.
+    engine = create_async_engine(
+        db_url,
+        echo=False,
+        poolclass=NullPool,  # No pooling - fresh connection per request
+        connect_args={
+            # Disable statement cache to avoid issues with prepared statements on reconnect
+            "statement_cache_size": 0,
+            # Allow 30s for commands (Neon cold start can take 2-5s, sometimes longer)
+            "command_timeout": 30,
+            # Allow 30s for initial connection (Neon wake-up time)
+            "timeout": 30,
+            "server_settings": {
+                "application_name": "basic-memory",
+                # Statement timeout for queries (30s to allow for cold start)
+                "statement_timeout": "30s",
+            },
+        },
+    )
+    logger.debug("Created Postgres engine with NullPool (no connection pooling)")
+
+    return engine
+
+
 def _create_engine_and_session(
-    db_path: Path, db_type: DatabaseType = DatabaseType.FILESYSTEM
+    db_path: Path,
+    db_type: DatabaseType = DatabaseType.FILESYSTEM,
+    config: Optional[BasicMemoryConfig] = None,
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
-    """Internal helper to create engine and session maker."""
-    db_url = DatabaseType.get_db_url(db_path, db_type)
+    """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, FILESYSTEM, or POSTGRES)
+        config: Optional explicit config. If not provided, reads from ConfigManager.
+            Prefer passing explicitly from composition roots.
+
+    Returns:
+        Tuple of (engine, session_maker)
+    """
+    # Prefer explicit parameter; fall back to ConfigManager for backwards compatibility
+    if config is None:
+        config = ConfigManager().config
+    db_url = DatabaseType.get_db_url(db_path, db_type, config)
     logger.debug(f"Creating engine for db_url: {db_url}")
-    engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
+
+    # Delegate to backend-specific engine creation
+    # Check explicit POSTGRES type first, then config setting
+    if db_type == DatabaseType.POSTGRES or config.database_backend == DatabaseBackend.POSTGRES:
+        engine = _create_postgres_engine(db_url, config)
+    else:
+        engine = _create_sqlite_engine(db_url, db_type)
+
     session_maker = async_sessionmaker(engine, expire_on_commit=False)
     return engine, session_maker
 
@@ -88,21 +278,29 @@ async def get_or_create_db(
     db_path: Path,
     db_type: DatabaseType = DatabaseType.FILESYSTEM,
     ensure_migrations: bool = True,
-    app_config: Optional["BasicMemoryConfig"] = None,
+    config: Optional[BasicMemoryConfig] = None,
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:  # pragma: no cover
-    """Get or create database engine and session maker."""
+    """Get or create database engine and session maker.
+
+    Args:
+        db_path: Path to database file
+        db_type: Type of database
+        ensure_migrations: Whether to run migrations
+        config: Optional explicit config. If not provided, reads from ConfigManager.
+            Prefer passing explicitly from composition roots.
+    """
     global _engine, _session_maker
 
+    # Prefer explicit parameter; fall back to ConfigManager for backwards compatibility
+    if config is None:
+        config = ConfigManager().config
+
     if _engine is None:
-        _engine, _session_maker = _create_engine_and_session(db_path, db_type)
+        _engine, _session_maker = _create_engine_and_session(db_path, db_type, config)
 
         # Run migrations automatically unless explicitly disabled
         if ensure_migrations:
-            if app_config is None:
-                from basic_memory.config import app_config as global_app_config
-
-                app_config = global_app_config
-            await run_migrations(app_config, db_type)
+            await run_migrations(config, db_type)
 
     # These checks should never fail since we just created the engine and session maker
     # if they were None, but we'll check anyway for the type checker
@@ -119,35 +317,37 @@ async def get_or_create_db(
 
 async def shutdown_db() -> None:  # pragma: no cover
     """Clean up database connections."""
-    global _engine, _session_maker, _migrations_completed
+    global _engine, _session_maker
 
     if _engine:
         await _engine.dispose()
         _engine = None
         _session_maker = None
-        _migrations_completed = False
 
 
 @asynccontextmanager
 async def engine_session_factory(
     db_path: Path,
     db_type: DatabaseType = DatabaseType.MEMORY,
+    config: Optional[BasicMemoryConfig] = None,
 ) -> AsyncGenerator[tuple[AsyncEngine, async_sessionmaker[AsyncSession]], None]:
     """Create engine and session factory.
 
     Note: This is primarily used for testing where we want a fresh database
     for each test. For production use, use get_or_create_db() instead.
+
+    Args:
+        db_path: Path to database file
+        db_type: Type of database
+        config: Optional explicit config. If not provided, reads from ConfigManager.
     """
 
-    global _engine, _session_maker, _migrations_completed
+    global _engine, _session_maker
 
-    db_url = DatabaseType.get_db_url(db_path, db_type)
-    logger.debug(f"Creating engine for db_url: {db_url}")
+    # Use the same helper function as production code
+    _engine, _session_maker = _create_engine_and_session(db_path, db_type, config)
 
-    _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")
@@ -163,20 +363,16 @@ 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, force: bool = False
+    app_config: BasicMemoryConfig, database_type=DatabaseType.FILESYSTEM
 ):  # pragma: no cover
-    """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
+    """Run any pending alembic migrations.
 
+    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
@@ -191,9 +387,11 @@ async def run_migrations(
         )
         config.set_main_option("timezone", "UTC")
         config.set_main_option("revision_environment", "false")
-        config.set_main_option(
-            "sqlalchemy.url", DatabaseType.get_db_url(app_config.database_path, database_type)
-        )
+
+        # Get the correct database URL based on backend configuration
+        # No URL conversion needed - env.py now handles both async and sync engines
+        db_url = DatabaseType.get_db_url(app_config.database_path, database_type, app_config)
+        config.set_main_option("sqlalchemy.url", db_url)
 
         command.upgrade(config, "head")
         logger.info("Migrations completed successfully")
@@ -204,12 +402,17 @@ async def run_migrations(
         else:
             session_maker = _session_maker
 
-        # 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
+        # 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 (
+            database_type == DatabaseType.POSTGRES
+            or app_config.database_backend == DatabaseBackend.POSTGRES
+        ):
+            await PostgresSearchRepository(session_maker, 1).init_search_index()
+        else:
+            await SQLiteSearchRepository(session_maker, 1).init_search_index()
     except Exception as e:  # pragma: no cover
         logger.error(f"Error running migrations: {e}")
         raise

src/basic_memory/deps.py

@@ -1,389 +1,16 @@
-"""Dependency injection functions for basic-memory services."""
-
-from typing import Annotated
-from loguru import logger
-
-from fastapi import Depends, HTTPException, Path, status
-from sqlalchemy.ext.asyncio import (
-    AsyncSession,
-    AsyncEngine,
-    async_sessionmaker,
-)
-import pathlib
-
-from basic_memory import db
-from basic_memory.config import ProjectConfig, BasicMemoryConfig
-from basic_memory.importers import (
-    ChatGPTImporter,
-    ClaudeConversationsImporter,
-    ClaudeProjectsImporter,
-    MemoryJsonImporter,
-)
-from basic_memory.markdown import EntityParser
-from basic_memory.markdown.markdown_processor import MarkdownProcessor
-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
-from basic_memory.services import EntityService, ProjectService
-from basic_memory.services.context_service import ContextService
-from basic_memory.services.directory_service import DirectoryService
-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.config import app_config
-
-
-def get_app_config() -> BasicMemoryConfig:  # pragma: no cover
-    return app_config
-
-
-AppConfigDep = Annotated[BasicMemoryConfig, Depends(get_app_config)]  # pragma: no cover
-
-
-## project
-
-
-async def get_project_config(
-    project: "ProjectPathDep", project_repository: "ProjectRepositoryDep"
-) -> ProjectConfig:  # pragma: no cover
-    """Get the current project referenced from request state.
-
-    Args:
-        request: The current request object
-        project_repository: Repository for project operations
-
-    Returns:
-        The resolved project config
-
-    Raises:
-        HTTPException: If project is not found
-    """
-
-    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))
-
-    # Not found
-    raise HTTPException(  # pragma: no cover
-        status_code=status.HTTP_404_NOT_FOUND, detail=f"Project '{project}' not found."
-    )
-
-
-ProjectConfigDep = Annotated[ProjectConfig, Depends(get_project_config)]  # pragma: no cover
-
-## sqlalchemy
-
-
-async def get_engine_factory(
-    app_config: AppConfigDep,
-) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:  # pragma: no cover
-    """Get engine and session maker."""
-    engine, session_maker = await db.get_or_create_db(app_config.database_path)
-    return engine, session_maker
-
-
-EngineFactoryDep = Annotated[
-    tuple[AsyncEngine, async_sessionmaker[AsyncSession]], Depends(get_engine_factory)
-]
-
-
-async def get_session_maker(engine_factory: EngineFactoryDep) -> async_sessionmaker[AsyncSession]:
-    """Get session maker."""
-    _, session_maker = engine_factory
-    return session_maker
-
-
-SessionMakerDep = Annotated[async_sessionmaker, Depends(get_session_maker)]
-
-
-## repositories
-
-
-async def get_project_repository(
-    session_maker: SessionMakerDep,
-) -> ProjectRepository:
-    """Get the project repository."""
-    return ProjectRepository(session_maker)
-
-
-ProjectRepositoryDep = Annotated[ProjectRepository, Depends(get_project_repository)]
-ProjectPathDep = Annotated[str, Path()]  # Use Path dependency to extract from URL
-
-
-async def get_project_id(
-    project_repository: ProjectRepositoryDep,
-    project: ProjectPathDep,
-) -> int:
-    """Get the current project ID from request state.
-
-    When using sub-applications with /{project} mounting, the project value
-    is stored in request.state by middleware.
-
-    Args:
-        request: The current request object
-        project_repository: Repository for project operations
-
-    Returns:
-        The resolved project ID
-
-    Raises:
-        HTTPException: If project is not found
-    """
-
-    # 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
-
-    # Try by name if permalink lookup fails
-    project_obj = await project_repository.get_by_name(str(project))  # pragma: no cover
-    if project_obj:  # pragma: no cover
-        return project_obj.id
-
-    # Not found
-    raise HTTPException(  # pragma: no cover
-        status_code=status.HTTP_404_NOT_FOUND, detail=f"Project '{project}' not found."
-    )
+"""Dependency injection functions for basic-memory services.
 
+DEPRECATED: This module is a backwards-compatibility shim.
+Import from basic_memory.deps package submodules instead:
+- basic_memory.deps.config for configuration
+- basic_memory.deps.db for database/session
+- basic_memory.deps.projects for project resolution
+- basic_memory.deps.repositories for data access
+- basic_memory.deps.services for business logic
+- basic_memory.deps.importers for import functionality
 
+This file will be removed once all callers are migrated.
 """
-The project_id dependency is used in the following:
-- EntityRepository
-- ObservationRepository
-- RelationRepository
-- SearchRepository
-- ProjectInfoRepository
-"""
-ProjectIdDep = Annotated[int, Depends(get_project_id)]
 
-
-async def get_entity_repository(
-    session_maker: SessionMakerDep,
-    project_id: ProjectIdDep,
-) -> EntityRepository:
-    """Create an EntityRepository instance for the current project."""
-    return EntityRepository(session_maker, project_id=project_id)
-
-
-EntityRepositoryDep = Annotated[EntityRepository, Depends(get_entity_repository)]
-
-
-async def get_observation_repository(
-    session_maker: SessionMakerDep,
-    project_id: ProjectIdDep,
-) -> ObservationRepository:
-    """Create an ObservationRepository instance for the current project."""
-    return ObservationRepository(session_maker, project_id=project_id)
-
-
-ObservationRepositoryDep = Annotated[ObservationRepository, Depends(get_observation_repository)]
-
-
-async def get_relation_repository(
-    session_maker: SessionMakerDep,
-    project_id: ProjectIdDep,
-) -> RelationRepository:
-    """Create a RelationRepository instance for the current project."""
-    return RelationRepository(session_maker, project_id=project_id)
-
-
-RelationRepositoryDep = Annotated[RelationRepository, Depends(get_relation_repository)]
-
-
-async def get_search_repository(
-    session_maker: SessionMakerDep,
-    project_id: ProjectIdDep,
-) -> SearchRepository:
-    """Create a SearchRepository instance for the current project."""
-    return SearchRepository(session_maker, project_id=project_id)
-
-
-SearchRepositoryDep = Annotated[SearchRepository, Depends(get_search_repository)]
-
-
-# ProjectInfoRepository is deprecated and will be removed in a future version.
-# Use ProjectRepository instead, which has the same functionality plus more project-specific operations.
-
-## services
-
-
-async def get_entity_parser(project_config: ProjectConfigDep) -> EntityParser:
-    return EntityParser(project_config.home)
-
-
-EntityParserDep = Annotated["EntityParser", Depends(get_entity_parser)]
-
-
-async def get_markdown_processor(entity_parser: EntityParserDep) -> MarkdownProcessor:
-    return MarkdownProcessor(entity_parser)
-
-
-MarkdownProcessorDep = Annotated[MarkdownProcessor, Depends(get_markdown_processor)]
-
-
-async def get_file_service(
-    project_config: ProjectConfigDep, markdown_processor: MarkdownProcessorDep
-) -> FileService:
-    logger.debug(
-        f"Creating FileService for project: {project_config.name}, base_path: {project_config.home}"
-    )
-    file_service = FileService(project_config.home, markdown_processor)
-    logger.debug(f"Created FileService for project: {file_service} ")
-    return file_service
-
-
-FileServiceDep = Annotated[FileService, Depends(get_file_service)]
-
-
-async def get_entity_service(
-    entity_repository: EntityRepositoryDep,
-    observation_repository: ObservationRepositoryDep,
-    relation_repository: RelationRepositoryDep,
-    entity_parser: EntityParserDep,
-    file_service: FileServiceDep,
-    link_resolver: "LinkResolverDep",
-) -> EntityService:
-    """Create EntityService with repository."""
-    return EntityService(
-        entity_repository=entity_repository,
-        observation_repository=observation_repository,
-        relation_repository=relation_repository,
-        entity_parser=entity_parser,
-        file_service=file_service,
-        link_resolver=link_resolver,
-    )
-
-
-EntityServiceDep = Annotated[EntityService, Depends(get_entity_service)]
-
-
-async def get_search_service(
-    search_repository: SearchRepositoryDep,
-    entity_repository: EntityRepositoryDep,
-    file_service: FileServiceDep,
-) -> SearchService:
-    """Create SearchService with dependencies."""
-    return SearchService(search_repository, entity_repository, file_service)
-
-
-SearchServiceDep = Annotated[SearchService, Depends(get_search_service)]
-
-
-async def get_link_resolver(
-    entity_repository: EntityRepositoryDep, search_service: SearchServiceDep
-) -> LinkResolver:
-    return LinkResolver(entity_repository=entity_repository, search_service=search_service)
-
-
-LinkResolverDep = Annotated[LinkResolver, Depends(get_link_resolver)]
-
-
-async def get_context_service(
-    search_repository: SearchRepositoryDep,
-    entity_repository: EntityRepositoryDep,
-    observation_repository: ObservationRepositoryDep,
-) -> ContextService:
-    return ContextService(
-        search_repository=search_repository,
-        entity_repository=entity_repository,
-        observation_repository=observation_repository,
-    )
-
-
-ContextServiceDep = Annotated[ContextService, Depends(get_context_service)]
-
-
-async def get_sync_service(
-    entity_service: EntityServiceDep,
-    entity_parser: EntityParserDep,
-    entity_repository: EntityRepositoryDep,
-    relation_repository: RelationRepositoryDep,
-    search_service: SearchServiceDep,
-    file_service: FileServiceDep,
-) -> SyncService:  # pragma: no cover
-    """
-
-    :rtype: object
-    """
-    return 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,
-    )
-
-
-SyncServiceDep = Annotated[SyncService, Depends(get_sync_service)]
-
-
-async def get_project_service(
-    project_repository: ProjectRepositoryDep,
-) -> ProjectService:
-    """Create ProjectService with repository."""
-    return ProjectService(repository=project_repository)
-
-
-ProjectServiceDep = Annotated[ProjectService, Depends(get_project_service)]
-
-
-async def get_directory_service(
-    entity_repository: EntityRepositoryDep,
-) -> DirectoryService:
-    """Create DirectoryService with dependencies."""
-    return DirectoryService(
-        entity_repository=entity_repository,
-    )
-
-
-DirectoryServiceDep = Annotated[DirectoryService, Depends(get_directory_service)]
-
-
-# Import
-
-
-async def get_chatgpt_importer(
-    project_config: ProjectConfigDep, markdown_processor: MarkdownProcessorDep
-) -> ChatGPTImporter:
-    """Create ChatGPTImporter with dependencies."""
-    return ChatGPTImporter(project_config.home, markdown_processor)
-
-
-ChatGPTImporterDep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer)]
-
-
-async def get_claude_conversations_importer(
-    project_config: ProjectConfigDep, markdown_processor: MarkdownProcessorDep
-) -> ClaudeConversationsImporter:
-    """Create ChatGPTImporter with dependencies."""
-    return ClaudeConversationsImporter(project_config.home, markdown_processor)
-
-
-ClaudeConversationsImporterDep = Annotated[
-    ClaudeConversationsImporter, Depends(get_claude_conversations_importer)
-]
-
-
-async def get_claude_projects_importer(
-    project_config: ProjectConfigDep, markdown_processor: MarkdownProcessorDep
-) -> ClaudeProjectsImporter:
-    """Create ChatGPTImporter with dependencies."""
-    return ClaudeProjectsImporter(project_config.home, markdown_processor)
-
-
-ClaudeProjectsImporterDep = Annotated[ClaudeProjectsImporter, Depends(get_claude_projects_importer)]
-
-
-async def get_memory_json_importer(
-    project_config: ProjectConfigDep, markdown_processor: MarkdownProcessorDep
-) -> MemoryJsonImporter:
-    """Create ChatGPTImporter with dependencies."""
-    return MemoryJsonImporter(project_config.home, markdown_processor)
-
-
-MemoryJsonImporterDep = Annotated[MemoryJsonImporter, Depends(get_memory_json_importer)]
+# Re-export everything from the deps package for backwards compatibility
+from basic_memory.deps import *  # noqa: F401, F403  # pragma: no cover

src/basic_memory/deps/__init__.py

@@ -0,0 +1,293 @@
+"""Dependency injection for basic-memory.
+
+This package provides FastAPI dependencies organized by feature:
+- config: Application configuration
+- db: Database/session management
+- projects: Project resolution and config
+- repositories: Data access layer
+- services: Business logic layer
+- importers: Import functionality
+
+For backwards compatibility, all dependencies are re-exported from this module.
+New code should import from specific submodules to reduce coupling.
+"""
+
+# Re-export everything for backwards compatibility
+# Eventually, callers should import from specific submodules
+
+from basic_memory.deps.config import (
+    get_app_config,
+    AppConfigDep,
+)
+
+from basic_memory.deps.db import (
+    get_engine_factory,
+    EngineFactoryDep,
+    get_session_maker,
+    SessionMakerDep,
+)
+
+from basic_memory.deps.projects import (
+    get_project_repository,
+    ProjectRepositoryDep,
+    ProjectPathDep,
+    get_project_id,
+    ProjectIdDep,
+    get_project_config,
+    ProjectConfigDep,
+    validate_project_id,
+    ProjectIdPathDep,
+    get_project_config_v2,
+    ProjectConfigV2Dep,
+    validate_project_external_id,
+    ProjectExternalIdPathDep,
+    get_project_config_v2_external,
+    ProjectConfigV2ExternalDep,
+)
+
+from basic_memory.deps.repositories import (
+    get_entity_repository,
+    EntityRepositoryDep,
+    get_entity_repository_v2,
+    EntityRepositoryV2Dep,
+    get_entity_repository_v2_external,
+    EntityRepositoryV2ExternalDep,
+    get_observation_repository,
+    ObservationRepositoryDep,
+    get_observation_repository_v2,
+    ObservationRepositoryV2Dep,
+    get_observation_repository_v2_external,
+    ObservationRepositoryV2ExternalDep,
+    get_relation_repository,
+    RelationRepositoryDep,
+    get_relation_repository_v2,
+    RelationRepositoryV2Dep,
+    get_relation_repository_v2_external,
+    RelationRepositoryV2ExternalDep,
+    get_search_repository,
+    SearchRepositoryDep,
+    get_search_repository_v2,
+    SearchRepositoryV2Dep,
+    get_search_repository_v2_external,
+    SearchRepositoryV2ExternalDep,
+)
+
+from basic_memory.deps.services import (
+    get_entity_parser,
+    EntityParserDep,
+    get_entity_parser_v2,
+    EntityParserV2Dep,
+    get_entity_parser_v2_external,
+    EntityParserV2ExternalDep,
+    get_markdown_processor,
+    MarkdownProcessorDep,
+    get_markdown_processor_v2,
+    MarkdownProcessorV2Dep,
+    get_markdown_processor_v2_external,
+    MarkdownProcessorV2ExternalDep,
+    get_file_service,
+    FileServiceDep,
+    get_file_service_v2,
+    FileServiceV2Dep,
+    get_file_service_v2_external,
+    FileServiceV2ExternalDep,
+    get_search_service,
+    SearchServiceDep,
+    get_search_service_v2,
+    SearchServiceV2Dep,
+    get_search_service_v2_external,
+    SearchServiceV2ExternalDep,
+    get_link_resolver,
+    LinkResolverDep,
+    get_link_resolver_v2,
+    LinkResolverV2Dep,
+    get_link_resolver_v2_external,
+    LinkResolverV2ExternalDep,
+    get_entity_service,
+    EntityServiceDep,
+    get_entity_service_v2,
+    EntityServiceV2Dep,
+    get_entity_service_v2_external,
+    EntityServiceV2ExternalDep,
+    get_context_service,
+    ContextServiceDep,
+    get_context_service_v2,
+    ContextServiceV2Dep,
+    get_context_service_v2_external,
+    ContextServiceV2ExternalDep,
+    get_sync_service,
+    SyncServiceDep,
+    get_sync_service_v2,
+    SyncServiceV2Dep,
+    get_sync_service_v2_external,
+    SyncServiceV2ExternalDep,
+    get_project_service,
+    ProjectServiceDep,
+    get_directory_service,
+    DirectoryServiceDep,
+    get_directory_service_v2,
+    DirectoryServiceV2Dep,
+    get_directory_service_v2_external,
+    DirectoryServiceV2ExternalDep,
+)
+
+from basic_memory.deps.importers import (
+    get_chatgpt_importer,
+    ChatGPTImporterDep,
+    get_chatgpt_importer_v2,
+    ChatGPTImporterV2Dep,
+    get_chatgpt_importer_v2_external,
+    ChatGPTImporterV2ExternalDep,
+    get_claude_conversations_importer,
+    ClaudeConversationsImporterDep,
+    get_claude_conversations_importer_v2,
+    ClaudeConversationsImporterV2Dep,
+    get_claude_conversations_importer_v2_external,
+    ClaudeConversationsImporterV2ExternalDep,
+    get_claude_projects_importer,
+    ClaudeProjectsImporterDep,
+    get_claude_projects_importer_v2,
+    ClaudeProjectsImporterV2Dep,
+    get_claude_projects_importer_v2_external,
+    ClaudeProjectsImporterV2ExternalDep,
+    get_memory_json_importer,
+    MemoryJsonImporterDep,
+    get_memory_json_importer_v2,
+    MemoryJsonImporterV2Dep,
+    get_memory_json_importer_v2_external,
+    MemoryJsonImporterV2ExternalDep,
+)
+
+__all__ = [
+    # Config
+    "get_app_config",
+    "AppConfigDep",
+    # Database
+    "get_engine_factory",
+    "EngineFactoryDep",
+    "get_session_maker",
+    "SessionMakerDep",
+    # Projects
+    "get_project_repository",
+    "ProjectRepositoryDep",
+    "ProjectPathDep",
+    "get_project_id",
+    "ProjectIdDep",
+    "get_project_config",
+    "ProjectConfigDep",
+    "validate_project_id",
+    "ProjectIdPathDep",
+    "get_project_config_v2",
+    "ProjectConfigV2Dep",
+    "validate_project_external_id",
+    "ProjectExternalIdPathDep",
+    "get_project_config_v2_external",
+    "ProjectConfigV2ExternalDep",
+    # Repositories
+    "get_entity_repository",
+    "EntityRepositoryDep",
+    "get_entity_repository_v2",
+    "EntityRepositoryV2Dep",
+    "get_entity_repository_v2_external",
+    "EntityRepositoryV2ExternalDep",
+    "get_observation_repository",
+    "ObservationRepositoryDep",
+    "get_observation_repository_v2",
+    "ObservationRepositoryV2Dep",
+    "get_observation_repository_v2_external",
+    "ObservationRepositoryV2ExternalDep",
+    "get_relation_repository",
+    "RelationRepositoryDep",
+    "get_relation_repository_v2",
+    "RelationRepositoryV2Dep",
+    "get_relation_repository_v2_external",
+    "RelationRepositoryV2ExternalDep",
+    "get_search_repository",
+    "SearchRepositoryDep",
+    "get_search_repository_v2",
+    "SearchRepositoryV2Dep",
+    "get_search_repository_v2_external",
+    "SearchRepositoryV2ExternalDep",
+    # Services
+    "get_entity_parser",
+    "EntityParserDep",
+    "get_entity_parser_v2",
+    "EntityParserV2Dep",
+    "get_entity_parser_v2_external",
+    "EntityParserV2ExternalDep",
+    "get_markdown_processor",
+    "MarkdownProcessorDep",
+    "get_markdown_processor_v2",
+    "MarkdownProcessorV2Dep",
+    "get_markdown_processor_v2_external",
+    "MarkdownProcessorV2ExternalDep",
+    "get_file_service",
+    "FileServiceDep",
+    "get_file_service_v2",
+    "FileServiceV2Dep",
+    "get_file_service_v2_external",
+    "FileServiceV2ExternalDep",
+    "get_search_service",
+    "SearchServiceDep",
+    "get_search_service_v2",
+    "SearchServiceV2Dep",
+    "get_search_service_v2_external",
+    "SearchServiceV2ExternalDep",
+    "get_link_resolver",
+    "LinkResolverDep",
+    "get_link_resolver_v2",
+    "LinkResolverV2Dep",
+    "get_link_resolver_v2_external",
+    "LinkResolverV2ExternalDep",
+    "get_entity_service",
+    "EntityServiceDep",
+    "get_entity_service_v2",
+    "EntityServiceV2Dep",
+    "get_entity_service_v2_external",
+    "EntityServiceV2ExternalDep",
+    "get_context_service",
+    "ContextServiceDep",
+    "get_context_service_v2",
+    "ContextServiceV2Dep",
+    "get_context_service_v2_external",
+    "ContextServiceV2ExternalDep",
+    "get_sync_service",
+    "SyncServiceDep",
+    "get_sync_service_v2",
+    "SyncServiceV2Dep",
+    "get_sync_service_v2_external",
+    "SyncServiceV2ExternalDep",
+    "get_project_service",
+    "ProjectServiceDep",
+    "get_directory_service",
+    "DirectoryServiceDep",
+    "get_directory_service_v2",
+    "DirectoryServiceV2Dep",
+    "get_directory_service_v2_external",
+    "DirectoryServiceV2ExternalDep",
+    # Importers
+    "get_chatgpt_importer",
+    "ChatGPTImporterDep",
+    "get_chatgpt_importer_v2",
+    "ChatGPTImporterV2Dep",
+    "get_chatgpt_importer_v2_external",
+    "ChatGPTImporterV2ExternalDep",
+    "get_claude_conversations_importer",
+    "ClaudeConversationsImporterDep",
+    "get_claude_conversations_importer_v2",
+    "ClaudeConversationsImporterV2Dep",
+    "get_claude_conversations_importer_v2_external",
+    "ClaudeConversationsImporterV2ExternalDep",
+    "get_claude_projects_importer",
+    "ClaudeProjectsImporterDep",
+    "get_claude_projects_importer_v2",
+    "ClaudeProjectsImporterV2Dep",
+    "get_claude_projects_importer_v2_external",
+    "ClaudeProjectsImporterV2ExternalDep",
+    "get_memory_json_importer",
+    "MemoryJsonImporterDep",
+    "get_memory_json_importer_v2",
+    "MemoryJsonImporterV2Dep",
+    "get_memory_json_importer_v2_external",
+    "MemoryJsonImporterV2ExternalDep",
+]

src/basic_memory/deps/config.py

@@ -0,0 +1,26 @@
+"""Configuration dependency injection for basic-memory.
+
+This module provides configuration-related dependencies.
+Note: Long-term goal is to minimize direct ConfigManager access
+and inject config from composition roots instead.
+"""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from basic_memory.config import BasicMemoryConfig, ConfigManager
+
+
+def get_app_config() -> BasicMemoryConfig:  # pragma: no cover
+    """Get the application configuration.
+
+    Note: This is a transitional dependency. The goal is for composition roots
+    to read ConfigManager and inject config explicitly. During migration,
+    this provides the same behavior as before.
+    """
+    app_config = ConfigManager().config
+    return app_config
+
+
+AppConfigDep = Annotated[BasicMemoryConfig, Depends(get_app_config)]

src/basic_memory/deps/db.py

@@ -0,0 +1,56 @@
+"""Database dependency injection for basic-memory.
+
+This module provides database-related dependencies:
+- Engine and session maker factories
+- Session dependencies for request handling
+"""
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from loguru import logger
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+)
+
+from basic_memory import db
+from basic_memory.deps.config import get_app_config
+
+
+async def get_engine_factory(
+    request: Request,
+) -> 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()
+    engine, session_maker = await db.get_or_create_db(app_config.database_path)
+    return engine, session_maker
+
+
+EngineFactoryDep = Annotated[
+    tuple[AsyncEngine, async_sessionmaker[AsyncSession]], Depends(get_engine_factory)
+]
+
+
+async def get_session_maker(engine_factory: EngineFactoryDep) -> async_sessionmaker[AsyncSession]:
+    """Get session maker."""
+    _, session_maker = engine_factory
+    return session_maker
+
+
+SessionMakerDep = Annotated[async_sessionmaker, Depends(get_session_maker)]

src/basic_memory/deps/importers.py

@@ -0,0 +1,200 @@
+"""Importer dependency injection for basic-memory.
+
+This module provides importer dependencies:
+- ChatGPTImporter
+- ClaudeConversationsImporter
+- ClaudeProjectsImporter
+- MemoryJsonImporter
+"""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from basic_memory.deps.projects import (
+    ProjectConfigDep,
+    ProjectConfigV2Dep,
+    ProjectConfigV2ExternalDep,
+)
+from basic_memory.deps.services import (
+    FileServiceDep,
+    FileServiceV2Dep,
+    FileServiceV2ExternalDep,
+    MarkdownProcessorDep,
+    MarkdownProcessorV2Dep,
+    MarkdownProcessorV2ExternalDep,
+)
+from basic_memory.importers import (
+    ChatGPTImporter,
+    ClaudeConversationsImporter,
+    ClaudeProjectsImporter,
+    MemoryJsonImporter,
+)
+
+
+# --- ChatGPT Importer ---
+
+
+async def get_chatgpt_importer(
+    project_config: ProjectConfigDep,
+    markdown_processor: MarkdownProcessorDep,
+    file_service: FileServiceDep,
+) -> ChatGPTImporter:
+    """Create ChatGPTImporter with dependencies."""
+    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+
+
+ChatGPTImporterDep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer)]
+
+
+async def get_chatgpt_importer_v2(  # pragma: no cover
+    project_config: ProjectConfigV2Dep,
+    markdown_processor: MarkdownProcessorV2Dep,
+    file_service: FileServiceV2Dep,
+) -> ChatGPTImporter:
+    """Create ChatGPTImporter with v2 dependencies."""
+    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+
+
+ChatGPTImporterV2Dep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer_v2)]
+
+
+async def get_chatgpt_importer_v2_external(
+    project_config: ProjectConfigV2ExternalDep,
+    markdown_processor: MarkdownProcessorV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+) -> ChatGPTImporter:
+    """Create ChatGPTImporter with v2 external_id dependencies."""
+    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+
+
+ChatGPTImporterV2ExternalDep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer_v2_external)]
+
+
+# --- Claude Conversations Importer ---
+
+
+async def get_claude_conversations_importer(
+    project_config: ProjectConfigDep,
+    markdown_processor: MarkdownProcessorDep,
+    file_service: FileServiceDep,
+) -> ClaudeConversationsImporter:
+    """Create ClaudeConversationsImporter with dependencies."""
+    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+
+
+ClaudeConversationsImporterDep = Annotated[
+    ClaudeConversationsImporter, Depends(get_claude_conversations_importer)
+]
+
+
+async def get_claude_conversations_importer_v2(  # pragma: no cover
+    project_config: ProjectConfigV2Dep,
+    markdown_processor: MarkdownProcessorV2Dep,
+    file_service: FileServiceV2Dep,
+) -> ClaudeConversationsImporter:
+    """Create ClaudeConversationsImporter with v2 dependencies."""
+    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+
+
+ClaudeConversationsImporterV2Dep = Annotated[
+    ClaudeConversationsImporter, Depends(get_claude_conversations_importer_v2)
+]
+
+
+async def get_claude_conversations_importer_v2_external(
+    project_config: ProjectConfigV2ExternalDep,
+    markdown_processor: MarkdownProcessorV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+) -> ClaudeConversationsImporter:
+    """Create ClaudeConversationsImporter with v2 external_id dependencies."""
+    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+
+
+ClaudeConversationsImporterV2ExternalDep = Annotated[
+    ClaudeConversationsImporter, Depends(get_claude_conversations_importer_v2_external)
+]
+
+
+# --- Claude Projects Importer ---
+
+
+async def get_claude_projects_importer(
+    project_config: ProjectConfigDep,
+    markdown_processor: MarkdownProcessorDep,
+    file_service: FileServiceDep,
+) -> ClaudeProjectsImporter:
+    """Create ClaudeProjectsImporter with dependencies."""
+    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+
+
+ClaudeProjectsImporterDep = Annotated[ClaudeProjectsImporter, Depends(get_claude_projects_importer)]
+
+
+async def get_claude_projects_importer_v2(  # pragma: no cover
+    project_config: ProjectConfigV2Dep,
+    markdown_processor: MarkdownProcessorV2Dep,
+    file_service: FileServiceV2Dep,
+) -> ClaudeProjectsImporter:
+    """Create ClaudeProjectsImporter with v2 dependencies."""
+    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+
+
+ClaudeProjectsImporterV2Dep = Annotated[
+    ClaudeProjectsImporter, Depends(get_claude_projects_importer_v2)
+]
+
+
+async def get_claude_projects_importer_v2_external(
+    project_config: ProjectConfigV2ExternalDep,
+    markdown_processor: MarkdownProcessorV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+) -> ClaudeProjectsImporter:
+    """Create ClaudeProjectsImporter with v2 external_id dependencies."""
+    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+
+
+ClaudeProjectsImporterV2ExternalDep = Annotated[
+    ClaudeProjectsImporter, Depends(get_claude_projects_importer_v2_external)
+]
+
+
+# --- Memory JSON Importer ---
+
+
+async def get_memory_json_importer(
+    project_config: ProjectConfigDep,
+    markdown_processor: MarkdownProcessorDep,
+    file_service: FileServiceDep,
+) -> MemoryJsonImporter:
+    """Create MemoryJsonImporter with dependencies."""
+    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+
+
+MemoryJsonImporterDep = Annotated[MemoryJsonImporter, Depends(get_memory_json_importer)]
+
+
+async def get_memory_json_importer_v2(  # pragma: no cover
+    project_config: ProjectConfigV2Dep,
+    markdown_processor: MarkdownProcessorV2Dep,
+    file_service: FileServiceV2Dep,
+) -> MemoryJsonImporter:
+    """Create MemoryJsonImporter with v2 dependencies."""
+    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+
+
+MemoryJsonImporterV2Dep = Annotated[MemoryJsonImporter, Depends(get_memory_json_importer_v2)]
+
+
+async def get_memory_json_importer_v2_external(
+    project_config: ProjectConfigV2ExternalDep,
+    markdown_processor: MarkdownProcessorV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+) -> MemoryJsonImporter:
+    """Create MemoryJsonImporter with v2 external_id dependencies."""
+    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+
+
+MemoryJsonImporterV2ExternalDep = Annotated[
+    MemoryJsonImporter, Depends(get_memory_json_importer_v2_external)
+]

src/basic_memory/deps/projects.py

@@ -0,0 +1,236 @@
+"""Project dependency injection for basic-memory.
+
+This module provides project-related dependencies:
+- Project path extraction from URL
+- Project config resolution
+- Project ID validation
+- Project repository
+"""
+
+import pathlib
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Path, status
+
+from basic_memory.config import ProjectConfig
+from basic_memory.deps.db import SessionMakerDep
+from basic_memory.repository.project_repository import ProjectRepository
+from basic_memory.utils import generate_permalink
+
+
+# --- Project Repository ---
+
+
+async def get_project_repository(
+    session_maker: SessionMakerDep,
+) -> ProjectRepository:
+    """Get the project repository."""
+    return ProjectRepository(session_maker)
+
+
+ProjectRepositoryDep = Annotated[ProjectRepository, Depends(get_project_repository)]
+
+
+# --- Path Extraction ---
+
+# V1 API: Project name from URL path
+ProjectPathDep = Annotated[str, Path()]
+
+
+# --- Project ID Resolution (V1 API) ---
+
+
+async def get_project_id(
+    project_repository: ProjectRepositoryDep,
+    project: ProjectPathDep,
+) -> int:
+    """Get the current project ID from request state.
+
+    When using sub-applications with /{project} mounting, the project value
+    is stored in request.state by middleware.
+
+    Args:
+        project_repository: Repository for project operations
+        project: The project name from URL path
+
+    Returns:
+        The resolved 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)
+    if project_obj:
+        return project_obj.id
+
+    # Try by name if permalink lookup fails
+    project_obj = await project_repository.get_by_name(str(project))  # pragma: no cover
+    if project_obj:  # pragma: no cover
+        return project_obj.id
+
+    # Not found
+    raise HTTPException(  # pragma: no cover
+        status_code=status.HTTP_404_NOT_FOUND, detail=f"Project '{project}' not found."
+    )
+
+
+ProjectIdDep = Annotated[int, Depends(get_project_id)]
+
+
+# --- Project Config Resolution (V1 API) ---
+
+
+async def get_project_config(
+    project: ProjectPathDep, project_repository: ProjectRepositoryDep
+) -> ProjectConfig:  # pragma: no cover
+    """Get the current project referenced from request state.
+
+    Args:
+        project: The project name from URL path
+        project_repository: Repository for project operations
+
+    Returns:
+        The resolved 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)
+    if project_obj:
+        return ProjectConfig(name=project_obj.name, home=pathlib.Path(project_obj.path))
+
+    # Not found
+    raise HTTPException(  # pragma: no cover
+        status_code=status.HTTP_404_NOT_FOUND, detail=f"Project '{project}' not found."
+    )
+
+
+ProjectConfigDep = Annotated[ProjectConfig, Depends(get_project_config)]
+
+
+# --- V2 API: Integer Project ID from Path ---
+
+
+async def validate_project_id(
+    project_id: int,
+    project_repository: ProjectRepositoryDep,
+) -> int:
+    """Validate that a numeric project ID exists in the database.
+
+    This is used for v2 API endpoints that take project IDs as integers in the path.
+    The project_id parameter will be automatically extracted from the URL path by FastAPI.
+
+    Args:
+        project_id: The numeric project ID from the URL path
+        project_repository: Repository for project operations
+
+    Returns:
+        The validated project ID
+
+    Raises:
+        HTTPException: If project with that ID is not found
+    """
+    project_obj = await project_repository.get_by_id(project_id)
+    if not project_obj:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Project with ID {project_id} not found.",
+        )
+    return project_id
+
+
+ProjectIdPathDep = Annotated[int, Depends(validate_project_id)]
+
+
+async def get_project_config_v2(
+    project_id: ProjectIdPathDep, project_repository: ProjectRepositoryDep
+) -> ProjectConfig:  # pragma: no cover
+    """Get the project config for v2 API (uses integer project_id from path).
+
+    Args:
+        project_id: The validated numeric project ID from the URL path
+        project_repository: Repository for project operations
+
+    Returns:
+        The resolved project config
+
+    Raises:
+        HTTPException: If project is not found
+    """
+    project_obj = await project_repository.get_by_id(project_id)
+    if project_obj:
+        return ProjectConfig(name=project_obj.name, home=pathlib.Path(project_obj.path))
+
+    # Not found (this should not happen since ProjectIdPathDep already validates existence)
+    raise HTTPException(  # pragma: no cover
+        status_code=status.HTTP_404_NOT_FOUND, detail=f"Project with ID {project_id} not found."
+    )
+
+
+ProjectConfigV2Dep = Annotated[ProjectConfig, Depends(get_project_config_v2)]
+
+
+# --- V2 API: External UUID Project ID from Path ---
+
+
+async def validate_project_external_id(
+    project_id: str,
+    project_repository: ProjectRepositoryDep,
+) -> int:
+    """Validate that a project external_id (UUID) exists in the database.
+
+    This is used for v2 API endpoints that take project external_ids as strings in the path.
+    The project_id parameter will be automatically extracted from the URL path by FastAPI.
+
+    Args:
+        project_id: The external UUID from the URL path (named project_id for URL consistency)
+        project_repository: Repository for project operations
+
+    Returns:
+        The internal numeric project ID (for use by repositories)
+
+    Raises:
+        HTTPException: If project with that external_id is not found
+    """
+    project_obj = await project_repository.get_by_external_id(project_id)
+    if not project_obj:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Project with external_id '{project_id}' not found.",
+        )
+    return project_obj.id
+
+
+ProjectExternalIdPathDep = Annotated[int, Depends(validate_project_external_id)]
+
+
+async def get_project_config_v2_external(
+    project_id: ProjectExternalIdPathDep, project_repository: ProjectRepositoryDep
+) -> ProjectConfig:  # pragma: no cover
+    """Get the project config for v2 API (uses external_id UUID from path).
+
+    Args:
+        project_id: The internal project ID resolved from external_id
+        project_repository: Repository for project operations
+
+    Returns:
+        The resolved project config
+
+    Raises:
+        HTTPException: If project is not found
+    """
+    project_obj = await project_repository.get_by_id(project_id)
+    if project_obj:
+        return ProjectConfig(name=project_obj.name, home=pathlib.Path(project_obj.path))
+
+    # Not found (this should not happen since ProjectExternalIdPathDep already validates)
+    raise HTTPException(  # pragma: no cover
+        status_code=status.HTTP_404_NOT_FOUND, detail=f"Project with ID {project_id} not found."
+    )
+
+
+ProjectConfigV2ExternalDep = Annotated[ProjectConfig, Depends(get_project_config_v2_external)]

src/basic_memory/deps/repositories.py

@@ -0,0 +1,183 @@
+"""Repository dependency injection for basic-memory.
+
+This module provides repository dependencies:
+- EntityRepository
+- ObservationRepository
+- RelationRepository
+- SearchRepository
+
+Each repository is scoped to a project ID from the request.
+"""
+
+from typing import Annotated
+
+from fastapi import Depends
+
+from basic_memory.deps.db import SessionMakerDep
+from basic_memory.deps.projects import (
+    ProjectIdDep,
+    ProjectIdPathDep,
+    ProjectExternalIdPathDep,
+)
+from basic_memory.repository.entity_repository import EntityRepository
+from basic_memory.repository.observation_repository import ObservationRepository
+from basic_memory.repository.relation_repository import RelationRepository
+from basic_memory.repository.search_repository import SearchRepository, create_search_repository
+
+
+# --- Entity Repository ---
+
+
+async def get_entity_repository(
+    session_maker: SessionMakerDep,
+    project_id: ProjectIdDep,
+) -> EntityRepository:
+    """Create an EntityRepository instance for the current project."""
+    return EntityRepository(session_maker, project_id=project_id)
+
+
+EntityRepositoryDep = Annotated[EntityRepository, Depends(get_entity_repository)]
+
+
+async def get_entity_repository_v2(  # pragma: no cover
+    session_maker: SessionMakerDep,
+    project_id: ProjectIdPathDep,
+) -> EntityRepository:
+    """Create an EntityRepository instance for v2 API (uses integer project_id from path)."""
+    return EntityRepository(session_maker, project_id=project_id)
+
+
+EntityRepositoryV2Dep = Annotated[EntityRepository, Depends(get_entity_repository_v2)]
+
+
+async def get_entity_repository_v2_external(
+    session_maker: SessionMakerDep,
+    project_id: ProjectExternalIdPathDep,
+) -> EntityRepository:
+    """Create an EntityRepository instance for v2 API (uses external_id from path)."""
+    return EntityRepository(session_maker, project_id=project_id)
+
+
+EntityRepositoryV2ExternalDep = Annotated[
+    EntityRepository, Depends(get_entity_repository_v2_external)
+]
+
+
+# --- Observation Repository ---
+
+
+async def get_observation_repository(
+    session_maker: SessionMakerDep,
+    project_id: ProjectIdDep,
+) -> ObservationRepository:
+    """Create an ObservationRepository instance for the current project."""
+    return ObservationRepository(session_maker, project_id=project_id)
+
+
+ObservationRepositoryDep = Annotated[ObservationRepository, Depends(get_observation_repository)]
+
+
+async def get_observation_repository_v2(  # pragma: no cover
+    session_maker: SessionMakerDep,
+    project_id: ProjectIdPathDep,
+) -> ObservationRepository:
+    """Create an ObservationRepository instance for v2 API."""
+    return ObservationRepository(session_maker, project_id=project_id)
+
+
+ObservationRepositoryV2Dep = Annotated[
+    ObservationRepository, Depends(get_observation_repository_v2)
+]
+
+
+async def get_observation_repository_v2_external(
+    session_maker: SessionMakerDep,
+    project_id: ProjectExternalIdPathDep,
+) -> ObservationRepository:
+    """Create an ObservationRepository instance for v2 API (uses external_id)."""
+    return ObservationRepository(session_maker, project_id=project_id)
+
+
+ObservationRepositoryV2ExternalDep = Annotated[
+    ObservationRepository, Depends(get_observation_repository_v2_external)
+]
+
+
+# --- Relation Repository ---
+
+
+async def get_relation_repository(
+    session_maker: SessionMakerDep,
+    project_id: ProjectIdDep,
+) -> RelationRepository:
+    """Create a RelationRepository instance for the current project."""
+    return RelationRepository(session_maker, project_id=project_id)
+
+
+RelationRepositoryDep = Annotated[RelationRepository, Depends(get_relation_repository)]
+
+
+async def get_relation_repository_v2(  # pragma: no cover
+    session_maker: SessionMakerDep,
+    project_id: ProjectIdPathDep,
+) -> RelationRepository:
+    """Create a RelationRepository instance for v2 API."""
+    return RelationRepository(session_maker, project_id=project_id)
+
+
+RelationRepositoryV2Dep = Annotated[RelationRepository, Depends(get_relation_repository_v2)]
+
+
+async def get_relation_repository_v2_external(
+    session_maker: SessionMakerDep,
+    project_id: ProjectExternalIdPathDep,
+) -> RelationRepository:
+    """Create a RelationRepository instance for v2 API (uses external_id)."""
+    return RelationRepository(session_maker, project_id=project_id)
+
+
+RelationRepositoryV2ExternalDep = Annotated[
+    RelationRepository, Depends(get_relation_repository_v2_external)
+]
+
+
+# --- Search Repository ---
+
+
+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)
+
+
+SearchRepositoryDep = Annotated[SearchRepository, Depends(get_search_repository)]
+
+
+async def get_search_repository_v2(  # pragma: no cover
+    session_maker: SessionMakerDep,
+    project_id: ProjectIdPathDep,
+) -> SearchRepository:
+    """Create a SearchRepository instance for v2 API."""
+    return create_search_repository(session_maker, project_id=project_id)
+
+
+SearchRepositoryV2Dep = Annotated[SearchRepository, Depends(get_search_repository_v2)]
+
+
+async def get_search_repository_v2_external(
+    session_maker: SessionMakerDep,
+    project_id: ProjectExternalIdPathDep,
+) -> SearchRepository:
+    """Create a SearchRepository instance for v2 API (uses external_id)."""
+    return create_search_repository(session_maker, project_id=project_id)
+
+
+SearchRepositoryV2ExternalDep = Annotated[
+    SearchRepository, Depends(get_search_repository_v2_external)
+]

src/basic_memory/deps/services.py

@@ -0,0 +1,484 @@
+"""Service dependency injection for basic-memory.
+
+This module provides service-layer dependencies:
+- EntityParser, MarkdownProcessor
+- FileService, EntityService
+- SearchService, LinkResolver, ContextService
+- SyncService, ProjectService, DirectoryService
+"""
+
+from typing import Annotated
+
+from fastapi import Depends
+from loguru import logger
+
+from basic_memory.deps.config import AppConfigDep
+from basic_memory.deps.projects import (
+    ProjectConfigDep,
+    ProjectConfigV2Dep,
+    ProjectConfigV2ExternalDep,
+    ProjectRepositoryDep,
+)
+from basic_memory.deps.repositories import (
+    EntityRepositoryDep,
+    EntityRepositoryV2Dep,
+    EntityRepositoryV2ExternalDep,
+    ObservationRepositoryDep,
+    ObservationRepositoryV2Dep,
+    ObservationRepositoryV2ExternalDep,
+    RelationRepositoryDep,
+    RelationRepositoryV2Dep,
+    RelationRepositoryV2ExternalDep,
+    SearchRepositoryDep,
+    SearchRepositoryV2Dep,
+    SearchRepositoryV2ExternalDep,
+)
+from basic_memory.markdown import EntityParser
+from basic_memory.markdown.markdown_processor import MarkdownProcessor
+from basic_memory.services import EntityService, ProjectService
+from basic_memory.services.context_service import ContextService
+from basic_memory.services.directory_service import DirectoryService
+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
+
+
+# --- Entity Parser ---
+
+
+async def get_entity_parser(project_config: ProjectConfigDep) -> EntityParser:
+    return EntityParser(project_config.home)
+
+
+EntityParserDep = Annotated["EntityParser", Depends(get_entity_parser)]
+
+
+async def get_entity_parser_v2(
+    project_config: ProjectConfigV2Dep,
+) -> EntityParser:  # pragma: no cover
+    return EntityParser(project_config.home)
+
+
+EntityParserV2Dep = Annotated["EntityParser", Depends(get_entity_parser_v2)]
+
+
+async def get_entity_parser_v2_external(project_config: ProjectConfigV2ExternalDep) -> EntityParser:
+    return EntityParser(project_config.home)
+
+
+EntityParserV2ExternalDep = Annotated["EntityParser", Depends(get_entity_parser_v2_external)]
+
+
+# --- Markdown Processor ---
+
+
+async def get_markdown_processor(
+    entity_parser: EntityParserDep, app_config: AppConfigDep
+) -> MarkdownProcessor:
+    return MarkdownProcessor(entity_parser, app_config=app_config)
+
+
+MarkdownProcessorDep = Annotated[MarkdownProcessor, Depends(get_markdown_processor)]
+
+
+async def get_markdown_processor_v2(  # pragma: no cover
+    entity_parser: EntityParserV2Dep, app_config: AppConfigDep
+) -> MarkdownProcessor:
+    return MarkdownProcessor(entity_parser, app_config=app_config)
+
+
+MarkdownProcessorV2Dep = Annotated[MarkdownProcessor, Depends(get_markdown_processor_v2)]
+
+
+async def get_markdown_processor_v2_external(
+    entity_parser: EntityParserV2ExternalDep, app_config: AppConfigDep
+) -> MarkdownProcessor:
+    return MarkdownProcessor(entity_parser, app_config=app_config)
+
+
+MarkdownProcessorV2ExternalDep = Annotated[
+    MarkdownProcessor, Depends(get_markdown_processor_v2_external)
+]
+
+
+# --- File Service ---
+
+
+async def get_file_service(
+    project_config: ProjectConfigDep,
+    markdown_processor: MarkdownProcessorDep,
+    app_config: AppConfigDep,
+) -> FileService:
+    file_service = FileService(project_config.home, markdown_processor, app_config=app_config)
+    logger.debug(
+        f"Created FileService for project: {project_config.name}, base_path: {project_config.home} "
+    )
+    return file_service
+
+
+FileServiceDep = Annotated[FileService, Depends(get_file_service)]
+
+
+async def get_file_service_v2(  # pragma: no cover
+    project_config: ProjectConfigV2Dep,
+    markdown_processor: MarkdownProcessorV2Dep,
+    app_config: AppConfigDep,
+) -> FileService:
+    file_service = FileService(project_config.home, markdown_processor, app_config=app_config)
+    logger.debug(
+        f"Created FileService for project: {project_config.name}, base_path: {project_config.home}"
+    )
+    return file_service
+
+
+FileServiceV2Dep = Annotated[FileService, Depends(get_file_service_v2)]
+
+
+async def get_file_service_v2_external(
+    project_config: ProjectConfigV2ExternalDep,
+    markdown_processor: MarkdownProcessorV2ExternalDep,
+    app_config: AppConfigDep,
+) -> FileService:
+    file_service = FileService(project_config.home, markdown_processor, app_config=app_config)
+    logger.debug(
+        f"Created FileService for project: {project_config.name}, base_path: {project_config.home}"
+    )
+    return file_service
+
+
+FileServiceV2ExternalDep = Annotated[FileService, Depends(get_file_service_v2_external)]
+
+
+# --- Search Service ---
+
+
+async def get_search_service(
+    search_repository: SearchRepositoryDep,
+    entity_repository: EntityRepositoryDep,
+    file_service: FileServiceDep,
+) -> SearchService:
+    """Create SearchService with dependencies."""
+    return SearchService(search_repository, entity_repository, file_service)
+
+
+SearchServiceDep = Annotated[SearchService, Depends(get_search_service)]
+
+
+async def get_search_service_v2(  # pragma: no cover
+    search_repository: SearchRepositoryV2Dep,
+    entity_repository: EntityRepositoryV2Dep,
+    file_service: FileServiceV2Dep,
+) -> SearchService:
+    """Create SearchService for v2 API."""
+    return SearchService(search_repository, entity_repository, file_service)
+
+
+SearchServiceV2Dep = Annotated[SearchService, Depends(get_search_service_v2)]
+
+
+async def get_search_service_v2_external(
+    search_repository: SearchRepositoryV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+) -> SearchService:
+    """Create SearchService for v2 API (uses external_id)."""
+    return SearchService(search_repository, entity_repository, file_service)
+
+
+SearchServiceV2ExternalDep = Annotated[SearchService, Depends(get_search_service_v2_external)]
+
+
+# --- Link Resolver ---
+
+
+async def get_link_resolver(
+    entity_repository: EntityRepositoryDep, search_service: SearchServiceDep
+) -> LinkResolver:
+    return LinkResolver(entity_repository=entity_repository, search_service=search_service)
+
+
+LinkResolverDep = Annotated[LinkResolver, Depends(get_link_resolver)]
+
+
+async def get_link_resolver_v2(  # pragma: no cover
+    entity_repository: EntityRepositoryV2Dep, search_service: SearchServiceV2Dep
+) -> LinkResolver:
+    return LinkResolver(entity_repository=entity_repository, search_service=search_service)
+
+
+LinkResolverV2Dep = Annotated[LinkResolver, Depends(get_link_resolver_v2)]
+
+
+async def get_link_resolver_v2_external(
+    entity_repository: EntityRepositoryV2ExternalDep, search_service: SearchServiceV2ExternalDep
+) -> LinkResolver:
+    return LinkResolver(entity_repository=entity_repository, search_service=search_service)
+
+
+LinkResolverV2ExternalDep = Annotated[LinkResolver, Depends(get_link_resolver_v2_external)]
+
+
+# --- Entity Service ---
+
+
+async def get_entity_service(
+    entity_repository: EntityRepositoryDep,
+    observation_repository: ObservationRepositoryDep,
+    relation_repository: RelationRepositoryDep,
+    entity_parser: EntityParserDep,
+    file_service: FileServiceDep,
+    link_resolver: LinkResolverDep,
+    search_service: SearchServiceDep,
+    app_config: AppConfigDep,
+) -> EntityService:
+    """Create EntityService with repository."""
+    return EntityService(
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+        relation_repository=relation_repository,
+        entity_parser=entity_parser,
+        file_service=file_service,
+        link_resolver=link_resolver,
+        search_service=search_service,
+        app_config=app_config,
+    )
+
+
+EntityServiceDep = Annotated[EntityService, Depends(get_entity_service)]
+
+
+async def get_entity_service_v2(  # pragma: no cover
+    entity_repository: EntityRepositoryV2Dep,
+    observation_repository: ObservationRepositoryV2Dep,
+    relation_repository: RelationRepositoryV2Dep,
+    entity_parser: EntityParserV2Dep,
+    file_service: FileServiceV2Dep,
+    link_resolver: LinkResolverV2Dep,
+    search_service: SearchServiceV2Dep,
+    app_config: AppConfigDep,
+) -> EntityService:
+    """Create EntityService for v2 API."""
+    return EntityService(
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+        relation_repository=relation_repository,
+        entity_parser=entity_parser,
+        file_service=file_service,
+        link_resolver=link_resolver,
+        search_service=search_service,
+        app_config=app_config,
+    )
+
+
+EntityServiceV2Dep = Annotated[EntityService, Depends(get_entity_service_v2)]
+
+
+async def get_entity_service_v2_external(
+    entity_repository: EntityRepositoryV2ExternalDep,
+    observation_repository: ObservationRepositoryV2ExternalDep,
+    relation_repository: RelationRepositoryV2ExternalDep,
+    entity_parser: EntityParserV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+    link_resolver: LinkResolverV2ExternalDep,
+    search_service: SearchServiceV2ExternalDep,
+    app_config: AppConfigDep,
+) -> EntityService:
+    """Create EntityService for v2 API (uses external_id)."""
+    return EntityService(
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+        relation_repository=relation_repository,
+        entity_parser=entity_parser,
+        file_service=file_service,
+        link_resolver=link_resolver,
+        search_service=search_service,
+        app_config=app_config,
+    )
+
+
+EntityServiceV2ExternalDep = Annotated[EntityService, Depends(get_entity_service_v2_external)]
+
+
+# --- Context Service ---
+
+
+async def get_context_service(
+    search_repository: SearchRepositoryDep,
+    entity_repository: EntityRepositoryDep,
+    observation_repository: ObservationRepositoryDep,
+) -> ContextService:
+    return ContextService(
+        search_repository=search_repository,
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+    )
+
+
+ContextServiceDep = Annotated[ContextService, Depends(get_context_service)]
+
+
+async def get_context_service_v2(  # pragma: no cover
+    search_repository: SearchRepositoryV2Dep,
+    entity_repository: EntityRepositoryV2Dep,
+    observation_repository: ObservationRepositoryV2Dep,
+) -> ContextService:
+    """Create ContextService for v2 API."""
+    return ContextService(
+        search_repository=search_repository,
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+    )
+
+
+ContextServiceV2Dep = Annotated[ContextService, Depends(get_context_service_v2)]
+
+
+async def get_context_service_v2_external(
+    search_repository: SearchRepositoryV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    observation_repository: ObservationRepositoryV2ExternalDep,
+) -> ContextService:
+    """Create ContextService for v2 API (uses external_id)."""
+    return ContextService(
+        search_repository=search_repository,
+        entity_repository=entity_repository,
+        observation_repository=observation_repository,
+    )
+
+
+ContextServiceV2ExternalDep = Annotated[ContextService, Depends(get_context_service_v2_external)]
+
+
+# --- Sync Service ---
+
+
+async def get_sync_service(
+    app_config: AppConfigDep,
+    entity_service: EntityServiceDep,
+    entity_parser: EntityParserDep,
+    entity_repository: EntityRepositoryDep,
+    relation_repository: RelationRepositoryDep,
+    project_repository: ProjectRepositoryDep,
+    search_service: SearchServiceDep,
+    file_service: FileServiceDep,
+) -> SyncService:  # pragma: no cover
+    return SyncService(
+        app_config=app_config,
+        entity_service=entity_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,
+    )
+
+
+SyncServiceDep = Annotated[SyncService, Depends(get_sync_service)]
+
+
+async def get_sync_service_v2(
+    app_config: AppConfigDep,
+    entity_service: EntityServiceV2Dep,
+    entity_parser: EntityParserV2Dep,
+    entity_repository: EntityRepositoryV2Dep,
+    relation_repository: RelationRepositoryV2Dep,
+    project_repository: ProjectRepositoryDep,
+    search_service: SearchServiceV2Dep,
+    file_service: FileServiceV2Dep,
+) -> SyncService:  # pragma: no cover
+    """Create SyncService for v2 API."""
+    return SyncService(
+        app_config=app_config,
+        entity_service=entity_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,
+    )
+
+
+SyncServiceV2Dep = Annotated[SyncService, Depends(get_sync_service_v2)]
+
+
+async def get_sync_service_v2_external(
+    app_config: AppConfigDep,
+    entity_service: EntityServiceV2ExternalDep,
+    entity_parser: EntityParserV2ExternalDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    relation_repository: RelationRepositoryV2ExternalDep,
+    project_repository: ProjectRepositoryDep,
+    search_service: SearchServiceV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+) -> SyncService:  # pragma: no cover
+    """Create SyncService for v2 API (uses external_id)."""
+    return SyncService(
+        app_config=app_config,
+        entity_service=entity_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,
+    )
+
+
+SyncServiceV2ExternalDep = Annotated[SyncService, Depends(get_sync_service_v2_external)]
+
+
+# --- Project Service ---
+
+
+async def get_project_service(
+    project_repository: ProjectRepositoryDep,
+) -> ProjectService:
+    """Create ProjectService with repository."""
+    return ProjectService(repository=project_repository)
+
+
+ProjectServiceDep = Annotated[ProjectService, Depends(get_project_service)]
+
+
+# --- Directory Service ---
+
+
+async def get_directory_service(
+    entity_repository: EntityRepositoryDep,
+) -> DirectoryService:
+    """Create DirectoryService with dependencies."""
+    return DirectoryService(
+        entity_repository=entity_repository,
+    )
+
+
+DirectoryServiceDep = Annotated[DirectoryService, Depends(get_directory_service)]
+
+
+async def get_directory_service_v2(  # pragma: no cover
+    entity_repository: EntityRepositoryV2Dep,
+) -> DirectoryService:
+    """Create DirectoryService for v2 API (uses integer project_id from path)."""
+    return DirectoryService(
+        entity_repository=entity_repository,
+    )
+
+
+DirectoryServiceV2Dep = Annotated[DirectoryService, Depends(get_directory_service_v2)]
+
+
+async def get_directory_service_v2_external(
+    entity_repository: EntityRepositoryV2ExternalDep,
+) -> DirectoryService:
+    """Create DirectoryService for v2 API (uses external_id from path)."""
+    return DirectoryService(
+        entity_repository=entity_repository,
+    )
+
+
+DirectoryServiceV2ExternalDep = Annotated[
+    DirectoryService, Depends(get_directory_service_v2_external)
+]

src/basic_memory/file_utils.py

@@ -1,14 +1,38 @@
 """Utilities for file operations."""
 
+import asyncio
 import hashlib
+import shlex
+from dataclasses import dataclass
+from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Union
+import re
+from typing import TYPE_CHECKING, Any, Dict, Optional, Union
 
+import aiofiles
 import yaml
+import frontmatter
 from loguru import logger
 
 from basic_memory.utils import FilePath
 
+if TYPE_CHECKING:  # pragma: no cover
+    from basic_memory.config import BasicMemoryConfig
+
+
+@dataclass
+class FileMetadata:
+    """File metadata for cloud-compatible file operations.
+
+    This dataclass provides a cloud-agnostic way to represent file metadata,
+    enabling S3FileService to return metadata from head_object responses
+    instead of mock stat_result with zeros.
+    """
+
+    size: int
+    created_at: datetime
+    modified_at: datetime
+
 
 class FileError(Exception):
     """Base exception for file operations."""
@@ -50,29 +74,34 @@ 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.
+# UTF-8 BOM character that can appear at the start of files
+UTF8_BOM = "\ufeff"
+
+
+def strip_bom(content: str) -> str:
+    """Strip UTF-8 BOM from the start of content if present.
+
+    BOM (Byte Order Mark) characters can be present in files created on Windows
+    or copied from certain sources. They should be stripped before processing
+    frontmatter. See issue #452.
 
     Args:
-        path: Directory path to ensure (Path or string)
+        content: Content that may start with BOM
 
-    Raises:
-        FileWriteError: If directory creation fails
+    Returns:
+        Content with BOM removed if present
     """
-    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}")
+    if content and content.startswith(UTF8_BOM):
+        return content[1:]
+    return content
 
 
 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
@@ -85,7 +114,11 @@ async def write_file_atomic(path: FilePath, content: str) -> None:
     temp_path = path_obj.with_suffix(".tmp")
 
     try:
-        temp_path.write_text(content, encoding="utf-8")
+        # 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.replace(path_obj)
         logger.debug("Wrote file atomically", path=str(path_obj), content_length=len(content))
     except Exception as e:  # pragma: no cover
@@ -94,6 +127,168 @@ async def write_file_atomic(path: FilePath, content: str) -> None:
         raise FileWriteError(f"Failed to write file {path}: {e}")
 
 
+async def format_markdown_builtin(path: Path) -> Optional[str]:
+    """
+    Format a markdown file using the built-in mdformat formatter.
+
+    Uses mdformat with GFM (GitHub Flavored Markdown) support for consistent
+    formatting without requiring Node.js or external tools.
+
+    Args:
+        path: Path to the markdown file to format
+
+    Returns:
+        Formatted content if successful, None if formatting failed.
+    """
+    try:
+        import mdformat
+    except ImportError:  # pragma: no cover
+        logger.warning(
+            "mdformat not installed, skipping built-in formatting",
+            path=str(path),
+        )
+        return None
+
+    try:
+        # Read original content
+        async with aiofiles.open(path, mode="r", encoding="utf-8") as f:
+            content = await f.read()
+
+        # Format using mdformat with GFM and frontmatter extensions
+        # mdformat is synchronous, so we run it in a thread executor
+        loop = asyncio.get_event_loop()
+        formatted_content = await loop.run_in_executor(
+            None,
+            lambda: mdformat.text(
+                content,
+                extensions={"gfm", "frontmatter"},  # GFM + YAML frontmatter support
+                options={"wrap": "no"},  # Don't wrap lines
+            ),
+        )
+
+        # Only write if content changed
+        if formatted_content != content:
+            async with aiofiles.open(path, mode="w", encoding="utf-8") as f:
+                await f.write(formatted_content)
+
+        logger.debug(
+            "Formatted file with mdformat",
+            path=str(path),
+            changed=formatted_content != content,
+        )
+        return formatted_content
+
+    except Exception as e:  # pragma: no cover
+        logger.warning(
+            "mdformat formatting failed",
+            path=str(path),
+            error=str(e),
+        )
+        return None
+
+
+async def format_file(
+    path: Path,
+    config: "BasicMemoryConfig",
+    is_markdown: bool = False,
+) -> Optional[str]:
+    """
+    Format a file using configured formatter.
+
+    By default, uses the built-in mdformat formatter for markdown files (pure Python,
+    no Node.js required). External formatters like Prettier can be configured via
+    formatter_command or per-extension formatters.
+
+    Args:
+        path: File to format
+        config: Configuration with formatter settings
+        is_markdown: Whether this is a markdown file (caller should use FileService.is_markdown)
+
+    Returns:
+        Formatted content if successful, None if formatting was skipped or failed.
+        Failures are logged as warnings but don't raise exceptions.
+    """
+    if not config.format_on_save:
+        return None
+
+    extension = path.suffix.lstrip(".")
+    formatter = config.formatters.get(extension) or config.formatter_command
+
+    # Use built-in mdformat for markdown files when no external formatter configured
+    if not formatter:
+        if is_markdown:
+            return await format_markdown_builtin(path)
+        else:
+            logger.debug("No formatter configured for extension", extension=extension)
+            return None
+
+    # Use external formatter
+    # Replace {file} placeholder with the actual path
+    cmd = formatter.replace("{file}", str(path))
+
+    try:
+        # Parse command into args list for safer execution (no shell=True)
+        args = shlex.split(cmd)
+
+        proc = await asyncio.create_subprocess_exec(
+            *args,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(),
+                timeout=config.formatter_timeout,
+            )
+        except asyncio.TimeoutError:
+            proc.kill()
+            await proc.wait()
+            logger.warning(
+                "Formatter timed out",
+                path=str(path),
+                timeout=config.formatter_timeout,
+            )
+            return None
+
+        if proc.returncode != 0:
+            logger.warning(
+                "Formatter exited with non-zero status",
+                path=str(path),
+                returncode=proc.returncode,
+                stderr=stderr.decode("utf-8", errors="replace") if stderr else "",
+            )
+            # Still try to read the file - formatter may have partially worked
+            # or the file may be unchanged
+
+        # Read formatted content
+        async with aiofiles.open(path, mode="r", encoding="utf-8") as f:
+            formatted_content = await f.read()
+
+        logger.debug(
+            "Formatted file successfully",
+            path=str(path),
+            formatter=args[0] if args else formatter,
+        )
+        return formatted_content
+
+    except FileNotFoundError:
+        # Formatter executable not found
+        logger.warning(
+            "Formatter executable not found",
+            command=cmd.split()[0] if cmd else "",
+            path=str(path),
+        )
+        return None
+    except Exception as e:  # pragma: no cover
+        logger.warning(
+            "Formatter failed",
+            path=str(path),
+            error=str(e),
+        )
+        return None
+
+
 def has_frontmatter(content: str) -> bool:
     """
     Check if content contains valid YAML frontmatter.
@@ -107,7 +302,8 @@ def has_frontmatter(content: str) -> bool:
     if not content:
         return False
 
-    content = content.strip()
+    # Strip BOM before checking for frontmatter markers
+    content = strip_bom(content).strip()
     if not content.startswith("---"):
         return False
 
@@ -128,6 +324,8 @@ def parse_frontmatter(content: str) -> Dict[str, Any]:
         ParseError: If frontmatter is invalid or parsing fails
     """
     try:
+        # Strip BOM before parsing frontmatter
+        content = strip_bom(content)
         if not content.strip().startswith("---"):
             raise ParseError("Content has no frontmatter")
 
@@ -169,7 +367,8 @@ def remove_frontmatter(content: str) -> str:
     Raises:
         ParseError: If content starts with frontmatter marker but is malformed
     """
-    content = content.strip()
+    # Strip BOM before processing
+    content = strip_bom(content).strip()
 
     # Return as-is if no frontmatter marker
     if not content.startswith("---"):
@@ -183,53 +382,97 @@ 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.
+def dump_frontmatter(post: frontmatter.Post) -> str:
+    """
+    Serialize frontmatter.Post to markdown with Obsidian-compatible YAML format.
 
-    Only modifies the frontmatter section, leaving all content untouched.
-    Creates frontmatter section if none exists.
-    Returns checksum of updated file.
+    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.)
+
+    Good (Obsidian compatible):
+    ---
+    title: "L2 Governance Core (Split: Core)"
+    tags:
+    - system
+    - overview
+    - reference
+    ---
+
+    Bad (causes parsing errors):
+    ---
+    title: L2 Governance Core (Split: Core)  # Unquoted colon breaks YAML
+    tags: ["system", "overview", "reference"]
+    ---
 
     Args:
-        path: Path to markdown file (Path or string)
-        updates: Dict of frontmatter fields to update
+        post: frontmatter.Post object to serialize
 
     Returns:
-        Checksum of updated file
-
-    Raises:
-        FileError: If file operations fail
-        ParseError: If frontmatter parsing fails
+        String containing markdown with properly formatted YAML frontmatter
     """
-    try:
-        # Convert string to Path if needed
-        path_obj = Path(path) if isinstance(path, str) else path
+    if not post.metadata:
+        # No frontmatter, just return content
+        return post.content
 
-        # Read current content
-        content = path_obj.read_text(encoding="utf-8")
+    # 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,
+    )
 
-        # Parse current frontmatter
-        current_fm = {}
-        if has_frontmatter(content):
-            current_fm = parse_frontmatter(content)
-            content = remove_frontmatter(content)
+    # Construct the final markdown with frontmatter
+    if post.content:
+        return f"---\n{yaml_str}---\n\n{post.content}"
+    else:
+        return f"---\n{yaml_str}---\n"
 
-        # 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()}"
+def sanitize_for_filename(text: str, replacement: str = "-") -> str:
+    """
+    Sanitize string to be safe for use as a note title
+    Replaces path separators and other problematic characters
+    with hyphens.
+    """
+    # replace both POSIX and Windows path separators
+    text = re.sub(r"[/\\]", replacement, text)
 
-        logger.debug("Updating frontmatter", path=str(path_obj), update_keys=list(updates.keys()))
+    # replace some other problematic chars
+    text = re.sub(r'[<>:"|?*]', replacement, text)
 
-        await write_file_atomic(path_obj, final_content)
-        return await compute_checksum(final_content)
+    # compress multiple, repeated replacements
+    text = re.sub(f"{re.escape(replacement)}+", replacement, text)
 
-    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}")
+    return text.strip(replacement)
+
+
+def sanitize_for_folder(folder: str) -> str:
+    """
+    Sanitize folder path to be safe for use in file system paths.
+    Removes leading/trailing whitespace, compresses multiple slashes,
+    and removes special characters except for /, -, and _.
+    """
+    if not folder:
+        return ""
+
+    sanitized = folder.strip()
+
+    if sanitized.startswith("./"):
+        sanitized = sanitized[2:]
+
+    # ensure no special characters (except for a few that are allowed)
+    sanitized = "".join(
+        c for c in sanitized if c.isalnum() or c in (".", " ", "-", "_", "\\", "/")
+    ).rstrip()
+
+    # compress multiple, repeated instances of path separators
+    sanitized = re.sub(r"[\\/]+", "/", sanitized)
+
+    # trim any leading/trailing path separators
+    sanitized = sanitized.strip("\\/")
+
+    return sanitized

src/basic_memory/ignore_utils.py

@@ -0,0 +1,297 @@
+"""Utilities for handling .gitignore patterns and file filtering."""
+
+import fnmatch
+from pathlib import Path
+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
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    # Obsidian
+    ".obsidian",
+    # Temporary files
+    "*.tmp",
+    "*.swp",
+    "*.swo",
+    "*~",
+}
+
+
+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:  # pragma: no cover
+        # If we can't read .bmignore, fall back to defaults
+        return set(DEFAULT_IGNORE_PATTERNS)  # pragma: no cover
+
+    # If no patterns were loaded, use defaults
+    if not patterns:  # pragma: no cover
+        return set(DEFAULT_IGNORE_PATTERNS)  # pragma: no cover
+
+    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)
+
+    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()
+
+    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
+
+    return patterns
+
+
+def should_ignore_path(file_path: Path, base_path: Path, ignore_patterns: Set[str]) -> bool:
+    """Check if a file path should be ignored based on gitignore patterns.
+
+    Args:
+        file_path: The file path to check
+        base_path: The base directory for relative path calculation
+        ignore_patterns: Set of patterns to match against
+
+    Returns:
+        True if the path should be ignored, False otherwise
+    """
+    # Get the relative path from base
+    try:
+        relative_path = file_path.relative_to(base_path)
+        relative_str = str(relative_path)
+        relative_posix = relative_path.as_posix()  # Use forward slashes for matching
+
+        # Check each pattern
+        for pattern in ignore_patterns:
+            # Handle patterns starting with / (root relative)
+            if pattern.startswith("/"):
+                root_pattern = pattern[1:]  # Remove leading /
+
+                # For directory patterns ending with /
+                if root_pattern.endswith("/"):
+                    dir_name = root_pattern[:-1]  # Remove trailing /
+                    # Check if the first part of the path matches the directory name
+                    if len(relative_path.parts) > 0 and relative_path.parts[0] == dir_name:
+                        return True
+                else:
+                    # Regular root-relative pattern
+                    if fnmatch.fnmatch(relative_posix, root_pattern):
+                        return True
+                continue
+
+            # Handle directory patterns (ending with /)
+            if pattern.endswith("/"):
+                dir_name = pattern[:-1]  # Remove trailing /
+                # Check if any path part matches the directory name
+                if dir_name in relative_path.parts:
+                    return True
+                continue
+
+            # Direct name match (e.g., ".git", "node_modules")
+            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
+            if fnmatch.fnmatch(relative_posix, pattern) or fnmatch.fnmatch(relative_str, pattern):
+                return True  # pragma: no cover
+
+        return False
+    except ValueError:
+        # If we can't get relative path, don't ignore
+        return False
+
+
+def filter_files(
+    files: list[Path], base_path: Path, ignore_patterns: Set[str] | None = None
+) -> tuple[list[Path], int]:
+    """Filter a list of files based on gitignore patterns.
+
+    Args:
+        files: List of file paths to filter
+        base_path: The base directory for relative path calculation
+        ignore_patterns: Set of patterns to ignore. If None, loads from .gitignore
+
+    Returns:
+        Tuple of (filtered_files, ignored_count)
+    """
+    if ignore_patterns is None:
+        ignore_patterns = load_gitignore_patterns(base_path)
+
+    filtered_files = []
+    ignored_count = 0
+
+    for file_path in files:
+        if should_ignore_path(file_path, base_path, ignore_patterns):
+            ignored_count += 1
+        else:
+            filtered_files.append(file_path)
+
+    return filtered_files, ignored_count