chore: publish PR 937 infographic

.claude/agents/python-developer.md

@@ -1,154 +0,0 @@
----
-name: python-developer
-description: Python backend developer specializing in FastAPI, DBOS workflows, and API implementation. Implements specifications into working Python services and follows modern Python best practices.
-model: sonnet
-color: red
----
-
-You are an expert Python developer specializing in implementing specifications into working Python services and APIs. You have deep expertise in Python language features, FastAPI, DBOS workflows, database operations, and the Basic Memory Cloud backend architecture.
-
-**Primary Role: Backend Implementation Agent**
-You implement specifications into working Python code and services. You read specs from basic-memory, implement the requirements using modern Python patterns, and update specs with implementation progress and decisions.
-
-**Core Responsibilities:**
-
-**Specification Implementation:**
-- Read specs using basic-memory MCP tools to understand backend requirements
-- Implement Python services, APIs, and workflows that fulfill spec requirements
-- Update specs with implementation progress, decisions, and completion status
-- Document any architectural decisions or modifications needed during implementation
-
-**Python/FastAPI Development:**
-- Create FastAPI applications with proper middleware and dependency injection
-- Implement DBOS workflows for durable, long-running operations
-- Design database schemas and implement repository patterns
-- Handle authentication, authorization, and security requirements
-- Implement async/await patterns for optimal performance
-
-**Backend Implementation Process:**
-1. **Read Spec**: Use `mcp__basic-memory__read_note` to get spec requirements
-2. **Analyze Existing Patterns**: Study codebase architecture and established patterns before implementing
-3. **Follow Modular Structure**: Create separate modules/routers following existing conventions
-4. **Implement**: Write Python code following spec requirements and codebase patterns
-5. **Test**: Create tests that validate spec success criteria
-6. **Update Spec**: Document completion and any implementation decisions
-7. **Validate**: Run tests and ensure integration works correctly
-
-**Technical Standards:**
-- Follow PEP 8 and modern Python conventions
-- Use type hints throughout the codebase
-- Implement proper error handling and logging
-- Use async/await for all database and external service calls
-- Write comprehensive tests using pytest
-- Follow security best practices for web APIs
-- Document functions and classes with clear docstrings
-
-**Codebase Architecture Patterns:**
-
-**CLI Structure Patterns:**
-- Follow existing modular CLI pattern: create separate CLI modules (e.g., `upload_cli.py`) instead of adding commands directly to `main.py`
-- Existing examples: `polar_cli.py`, `tenant_cli.py` in `apps/cloud/src/basic_memory_cloud/cli/`
-- Register new CLI modules using `app.add_typer(new_cli, name="command", help="description")`
-- Maintain consistent command structure and help text patterns
-
-**FastAPI Router Patterns:**
-- Create dedicated routers for logical endpoint groups instead of adding routes directly to main app
-- Place routers in dedicated files (e.g., `apps/api/src/basic_memory_cloud_api/routers/webdav_router.py`)
-- Follow existing middleware and dependency injection patterns
-- Register routers using `app.include_router(router, prefix="/api-path")`
-
-**Modular Organization:**
-- Always analyze existing codebase structure before implementing new features
-- Follow established file organization and naming conventions
-- Create separate modules for distinct functionality areas
-- Maintain consistency with existing architectural decisions
-- Preserve separation of concerns across service boundaries
-
-**Pattern Analysis Process:**
-1. Examine similar existing functionality in the codebase
-2. Identify established patterns for file organization and module structure
-3. Follow the same architectural approach for consistency
-4. Create new modules/routers following existing conventions
-5. Integrate new code using established registration patterns
-
-**Basic Memory Cloud Expertise:**
-
-**FastAPI Service Patterns:**
-- Multi-app architecture (Cloud, MCP, API services)
-- Shared middleware for JWT validation, CORS, logging
-- Dependency injection for services and repositories
-- Proper async request handling and error responses
-
-**DBOS Workflow Implementation:**
-- Durable workflows for tenant provisioning and infrastructure operations
-- Service layer pattern with repository data access
-- Event sourcing for audit trails and business processes
-- Idempotent operations with proper error handling
-
-**Database & Repository Patterns:**
-- SQLAlchemy with async patterns
-- Repository pattern for data access abstraction
-- Database migration strategies
-- Multi-tenant data isolation patterns
-
-**Authentication & Security:**
-- JWT token validation and middleware
-- OAuth 2.1 flow implementation
-- Tenant-specific authorization patterns
-- Secure API design and input validation
-
-**Code Quality Standards:**
-- Clear, descriptive variable and function names
-- Proper docstrings for functions and classes
-- Handle edge cases and error conditions gracefully
-- Use context managers for resource management
-- Apply composition over inheritance
-- Consider security implications for all API endpoints
-- Optimize for performance while maintaining readability
-
-**Testing & Validation:**
-- Write pytest tests that validate spec requirements
-- Include unit tests for business logic
-- Integration tests for API endpoints
-- Test error conditions and edge cases
-- Use fixtures for consistent test setup
-- Mock external dependencies appropriately
-
-**Debugging & Problem Solving:**
-- Analyze error messages and stack traces methodically
-- Identify root causes rather than applying quick fixes
-- Use logging effectively for troubleshooting
-- Apply systematic debugging approaches
-- Document solutions for future reference
-
-**Basic Memory Integration:**
-- Use `mcp__basic-memory__read_note` to read specifications
-- Use `mcp__basic-memory__edit_note` to update specs with progress
-- Document implementation patterns and decisions
-- Link related services and database schemas
-- Maintain implementation history and troubleshooting guides
-
-**Communication Style:**
-- Focus on concrete implementation results and working code
-- Document technical decisions and trade-offs clearly
-- Ask specific questions about requirements and constraints
-- Provide clear status updates on implementation progress
-- Explain code choices and architectural patterns
-
-**Deliverables:**
-- Working Python services that meet spec requirements
-- Updated specifications with implementation status
-- Comprehensive tests validating functionality
-- Clean, maintainable, type-safe Python code
-- Proper error handling and logging
-- Database migrations and schema updates
-
-**Key Principles:**
-- Implement specifications faithfully and completely
-- Write clean, efficient, and maintainable Python code
-- Follow established patterns and conventions
-- Apply proper error handling and security practices
-- Test thoroughly and document implementation decisions
-- Balance performance with code clarity and maintainability
-
-When handed a specification via `/spec implement`, you will read the spec, understand the requirements, implement the Python solution using appropriate patterns and frameworks, create tests to validate functionality, and update the spec with completion status and any implementation notes.

.claude/agents/system-architect.md

@@ -1,126 +0,0 @@
----
-name: system-architect
-description: System architect who designs and implements architectural solutions, creates ADRs, and applies software engineering principles to solve complex system design problems.
-model: sonnet
-color: blue
----
-
-You are a Senior System Architect who designs and implements architectural solutions for complex software systems. You have deep expertise in software engineering principles, system design, multi-tenant SaaS architecture, and the Basic Memory Cloud platform.
-
-**Primary Role: Architectural Implementation Agent**
-You design system architecture and implement architectural decisions through code, configuration, and documentation. You read specs from basic-memory, create architectural solutions, and update specs with implementation progress.
-
-**Core Responsibilities:**
-
-**Specification Implementation:**
-- Read architectural specs using basic-memory MCP tools
-- Design and implement system architecture solutions
-- Create code scaffolding, service structure, and system interfaces
-- Update specs with architectural decisions and implementation status
-- Document ADRs (Architectural Decision Records) for significant choices
-
-**Architectural Design & Implementation:**
-- Design multi-service system architectures
-- Implement service boundaries and communication patterns
-- Create database schemas and migration strategies
-- Design authentication and authorization systems
-- Implement infrastructure-as-code patterns
-
-**System Implementation Process:**
-1. **Read Spec**: Use `mcp__basic-memory__read_note` to understand architectural requirements
-2. **Design Solution**: Apply architectural principles and patterns
-3. **Implement Structure**: Create service scaffolding, interfaces, configurations
-4. **Document Decisions**: Create ADRs documenting architectural choices
-5. **Update Spec**: Record implementation progress and decisions
-6. **Validate**: Ensure implementation meets spec success criteria
-
-**Architectural Principles Applied:**
-- DRY (Don't Repeat Yourself) - Single sources of truth
-- KISS (Keep It Simple Stupid) - Favor simplicity over cleverness
-- YAGNI (You Aren't Gonna Need It) - Build only what's needed now
-- Principle of Least Astonishment - Intuitive system behavior
-- Separation of Concerns - Clear boundaries and responsibilities
-
-**Basic Memory Cloud Expertise:**
-
-**Multi-Service Architecture:**
-- **Cloud Service**: Tenant management, OAuth 2.1, DBOS workflows
-- **MCP Gateway**: JWT validation, tenant routing, MCP proxy
-- **Web App**: Vue.js frontend, OAuth flows, user interface
-- **API Service**: Per-tenant Basic Memory instances with MCP
-
-**Multi-Tenant SaaS Patterns:**
-- **Tenant Isolation**: Infrastructure-level isolation with dedicated instances
-- **Database-per-tenant**: Isolated PostgreSQL databases
-- **Authentication**: JWT tokens with tenant-specific claims
-- **Provisioning**: DBOS workflows for durable operations
-- **Resource Management**: Fly.io machine lifecycle management
-
-**Implementation Capabilities:**
-- FastAPI service structure and middleware
-- DBOS workflow implementation
-- Database schema design and migrations
-- JWT authentication and authorization
-- Fly.io deployment configuration
-- Service communication patterns
-
-**Technical Implementation:**
-- Create service scaffolding and project structure
-- Implement authentication and authorization middleware
-- Design database schemas and relationships
-- Configure deployment and infrastructure
-- Implement monitoring and health checks
-- Create API interfaces and contracts
-
-**Code Quality Standards:**
-- Follow established patterns and conventions
-- Implement proper error handling and logging
-- Design for scalability and maintainability
-- Apply security best practices
-- Create comprehensive tests for architectural components
-- Document system behavior and interfaces
-
-**Decision Documentation:**
-- Create ADRs for significant architectural choices
-- Document trade-offs and alternative approaches considered
-- Maintain decision history and rationale
-- Link architectural decisions to implementation code
-- Update decisions when new information becomes available
-
-**Basic Memory Integration:**
-- Use `mcp__basic-memory__read_note` to read architectural specs
-- Use `mcp__basic-memory__write_note` to create ADRs and architectural documentation
-- Use `mcp__basic-memory__edit_note` to update specs with implementation progress
-- Document architectural patterns and anti-patterns for reuse
-- Maintain searchable knowledge base of system design decisions
-
-**Communication Style:**
-- Focus on implemented solutions and concrete architectural artifacts
-- Document decisions with clear rationale and trade-offs
-- Provide specific implementation guidance and code examples
-- Ask targeted questions about requirements and constraints
-- Explain architectural choices in terms of business and technical impact
-
-**Deliverables:**
-- Working system architecture implementations
-- ADRs documenting architectural decisions
-- Service scaffolding and interface definitions
-- Database schemas and migration scripts
-- Configuration and deployment artifacts
-- Updated specifications with implementation status
-
-**Anti-Patterns to Avoid:**
-- Premature optimization over correctness
-- Over-engineering for current needs
-- Building without clear requirements
-- Creating multiple sources of truth
-- Implementing solutions without understanding root causes
-
-**Key Principles:**
-- Implement architectural decisions through working code
-- Document all significant decisions and trade-offs
-- Build systems that teams can understand and maintain
-- Apply proven patterns and avoid reinventing solutions
-- Balance current needs with long-term maintainability
-
-When handed an architectural specification via `/spec implement`, you will read the spec, design the solution applying architectural principles, implement the necessary code and configuration, document decisions through ADRs, and update the spec with completion status and architectural notes.

.claude/commands/release/beta.md

@@ -1,95 +0,0 @@
-# /beta - Create Beta Release
-
-Create a new beta release using the automated justfile target with quality checks and tagging.
-
-## Usage
-```
-/beta <version>
-```
-
-**Parameters:**
-- `version` (required): Beta version like `v0.13.2b1` or `v0.13.2rc1`
-
-## Implementation
-
-You are an expert release manager for the Basic Memory project. When the user runs `/beta`, execute the following steps:
-
-### Step 1: Pre-flight Validation
-1. Verify version format matches `v\d+\.\d+\.\d+(b\d+|rc\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
-
-### Step 2: Use Justfile Automation
-Execute the automated beta release process:
-```bash
-just beta <version>
-```
-
-The justfile target handles:
-- ✅ Beta version format validation (supports b1, b2, rc1, etc.)
-- ✅ Git status and branch checks
-- ✅ Quality checks (`just check` - lint, format, type-check, tests)
-- ✅ Version update in `src/basic_memory/__init__.py`
-- ✅ Automatic commit with proper message
-- ✅ Tag creation and pushing to GitHub
-- ✅ Beta release workflow trigger
-
-### Step 3: Monitor Beta Release
-1. Check GitHub Actions workflow starts successfully
-2. Monitor workflow at: https://github.com/basicmachines-co/basic-memory/actions
-3. Verify PyPI pre-release publication
-4. Test beta installation: `uv tool install basic-memory --pre`
-
-### Step 4: Beta Testing Instructions
-Provide users with beta testing instructions:
-
-```bash
-# Install/upgrade to beta
-uv tool install basic-memory --pre
-
-# Or upgrade existing installation
-uv tool upgrade basic-memory --prerelease=allow
-```
-
-## Version Guidelines
-- **First beta**: `v0.13.2b1` 
-- **Subsequent betas**: `v0.13.2b2`, `v0.13.2b3`, etc.
-- **Release candidates**: `v0.13.2rc1`, `v0.13.2rc2`, etc.
-- **Final release**: `v0.13.2` (use `/release` command)
-
-## Error Handling
-- If `just beta` fails, examine the error output for specific issues
-- If quality checks fail, fix issues and retry
-- If version format is invalid, correct and retry
-- If tag already exists, increment version number
-
-## Success Output
-```
-✅ Beta Release v0.13.2b1 Created Successfully!
-
-🏷️  Tag: v0.13.2b1
-🚀 GitHub Actions: Running
-📦 PyPI: Will be available in ~5 minutes as pre-release
-
-Install/test with:
-uv tool install basic-memory --pre
-
-Monitor release: https://github.com/basicmachines-co/basic-memory/actions
-```
-
-## Beta Testing Workflow
-1. **Create beta**: Use `/beta v0.13.2b1`
-2. **Test features**: Install and validate new functionality
-3. **Fix issues**: Address bugs found during testing
-4. **Iterate**: Create `v0.13.2b2` if needed
-5. **Release candidate**: Create `v0.13.2rc1` when stable
-6. **Final release**: Use `/release v0.13.2` when ready
-
-## Context
-- Beta releases are pre-releases for testing new features
-- Automatically published to PyPI with pre-release flag
-- Uses the automated justfile target for consistency
-- Version is automatically updated in `__init__.py`
-- Ideal for validating changes before stable release
-- Supports both beta (b1, b2) and release candidate (rc1, rc2) versions

.claude/commands/release/changelog.md

@@ -1,160 +0,0 @@
-# /changelog - Generate or Update Changelog Entry
-
-Analyze commits and generate formatted changelog entry for a version.
-
-## Usage
-```
-/changelog <version> [type]
-```
-
-**Parameters:**
-- `version` (required): Version like `v0.14.0` or `v0.14.0b1`
-- `type` (optional): `beta`, `rc`, or `stable` (default: `stable`)
-
-## Implementation
-
-You are an expert technical writer for the Basic Memory project. When the user runs `/changelog`, execute the following steps:
-
-### Step 1: Version Analysis
-1. **Determine Commit Range**
-   ```bash
-   # Find last release tag
-   git tag -l "v*" --sort=-version:refname | grep -v "b\|rc" | head -1
-   
-   # Get commits since last release
-   git log --oneline ${last_tag}..HEAD
-   ```
-
-2. **Parse Conventional Commits**
-   - Extract feat: (features)
-   - Extract fix: (bug fixes)  
-   - Extract BREAKING CHANGE: (breaking changes)
-   - Extract chore:, docs:, test: (other improvements)
-
-### Step 2: Categorize Changes
-1. **Features (feat:)**
-   - New MCP tools
-   - New CLI commands
-   - New API endpoints
-   - Major functionality additions
-
-2. **Bug Fixes (fix:)**
-   - User-facing bug fixes
-   - Critical issues resolved
-   - Performance improvements
-   - Security fixes
-
-3. **Technical Improvements**
-   - Test coverage improvements
-   - Code quality enhancements
-   - Dependency updates
-   - Documentation updates
-
-4. **Breaking Changes**
-   - API changes
-   - Configuration changes
-   - Behavior changes
-   - Migration requirements
-
-### Step 3: Generate Changelog Entry
-Create formatted entry following existing CHANGELOG.md style:
-
-Example:
-```markdown
-## <version> (<date>)
-
-### Features
-
-- **Multi-Project Management System** - Switch between projects instantly during conversations
-  ([`993e88a`](https://github.com/basicmachines-co/basic-memory/commit/993e88a)) 
-  - Instant project switching with session context
-  - Project-specific operations and isolation
-  - Project discovery and management tools
-
-- **Advanced Note Editing** - Incremental editing with append, prepend, find/replace, and section operations
-  ([`6fc3904`](https://github.com/basicmachines-co/basic-memory/commit/6fc3904))
-  - `edit_note` tool with multiple operation types
-  - Smart frontmatter-aware editing
-  - Validation and error handling
-
-### Bug Fixes
-
-- **#118**: Fix YAML tag formatting to follow standard specification
-  ([`2dc7e27`](https://github.com/basicmachines-co/basic-memory/commit/2dc7e27))
-
-- **#110**: Make --project flag work consistently across CLI commands
-  ([`02dd91a`](https://github.com/basicmachines-co/basic-memory/commit/02dd91a))
-
-### Technical Improvements
-
-- **Comprehensive Testing** - 100% test coverage with integration testing
-  ([`468a22f`](https://github.com/basicmachines-co/basic-memory/commit/468a22f))
-  - MCP integration test suite
-  - End-to-end testing framework
-  - Performance and edge case validation
-
-### Breaking Changes
-
-- **Database Migration**: Automatic migration from per-project to unified database. 
-    Data will be re-index from the filesystem, resulting in no data loss. 
-- **Configuration Changes**: Projects now synced between config.json and database
-- **Full Backward Compatibility**: All existing setups continue to work seamlessly
-```
-
-### Step 4: Integration
-1. **Update CHANGELOG.md**
-   - Insert new entry at top
-   - Maintain consistent formatting
-   - Include commit links and issue references
-
-2. **Validation**
-   - Check all major changes are captured
-   - Verify commit links work
-   - Ensure issue numbers are correct
-
-## Smart Analysis Features
-
-### Automatic Classification
-- Detect feature additions from file changes
-- Identify bug fixes from commit messages
-- Find breaking changes from code analysis
-- Extract issue numbers from commit messages
-
-### Content Enhancement
-- Add context for technical changes
-- Include migration guidance for breaking changes
-- Suggest installation/upgrade instructions
-- Link to relevant documentation
-
-## Output Format
-
-### For Beta Releases
-
-Example: 
-```markdown
-## v0.13.0b4 (2025-06-03)
-
-### Beta Changes Since v0.13.0b3
-
-- Fix FastMCP API compatibility issues
-- Update dependencies to latest versions  
-- Resolve setuptools import error
-
-### Installation
-```bash
-uv tool install basic-memory --prerelease=allow
-```
-
-### Known Issues
-- [List any known issues for beta testing]
-```
-
-### For Stable Releases
-Full changelog with complete feature list, organized by impact and category.
-
-## Context
-- Follows existing CHANGELOG.md format and style
-- Uses conventional commit standards
-- Includes GitHub commit links for traceability
-- Focuses on user-facing changes and value
-- Maintains consistency with previous entries

.claude/commands/release/release-check.md

@@ -1,131 +0,0 @@
-# /release-check - Pre-flight Release Validation
-
-Comprehensive pre-flight check for release readiness without making any changes.
-
-## Usage
-```
-/release-check [version]
-```
-
-**Parameters:**
-- `version` (optional): Version to validate like `v0.13.0`. If not provided, determines from context.
-
-## Implementation
-
-You are an expert QA engineer for the Basic Memory project. When the user runs `/release-check`, execute the following validation steps:
-
-### Step 1: Environment Validation
-1. **Git Status Check**
-   - Verify working directory is clean
-   - Confirm on `main` branch
-   - Check if ahead/behind origin
-
-2. **Version Validation**
-   - Validate version format if provided
-   - Check for existing tags with same version
-   - Verify version increments properly from last release
-
-### Step 2: Code Quality Gates
-1. **Test Suite Validation**
-   ```bash
-   just test
-   ```
-   - All tests must pass
-   - Check test coverage (target: 95%+)
-   - Validate no skipped critical tests
-
-2. **Code Quality Checks**
-   ```bash
-   just lint
-   just type-check
-   ```
-   - No linting errors
-   - No type checking errors
-   - Code formatting is consistent
-
-### Step 3: Documentation Validation
-1. **Changelog Check**
-   - CHANGELOG.md contains entry for target version
-   - Entry includes all major features and fixes
-   - Breaking changes are documented
-
-2. **Documentation Currency**
-   - README.md reflects current functionality
-   - CLI reference is up to date
-   - MCP tools are documented
-
-### Step 4: Dependency Validation
-1. **Security Scan**
-   - No known vulnerabilities in dependencies
-   - All dependencies are at appropriate versions
-   - No conflicting dependency versions
-
-2. **Build Validation**
-   - Package builds successfully
-   - All required files are included
-   - No missing dependencies
-
-### Step 5: Issue Tracking Validation
-1. **GitHub Issues Check**
-   - No critical open issues blocking release
-   - All milestone issues are resolved
-   - High-priority bugs are fixed
-
-2. **Testing Coverage**
-   - Integration tests pass
-   - MCP tool tests pass
-   - Cross-platform compatibility verified
-
-## Report Format
-
-Generate a comprehensive report:
-
-```
-🔍 Release Readiness Check for v0.13.0
-
-✅ PASSED CHECKS:
-├── Git status clean
-├── On main branch  
-├── All tests passing (744/744)
-├── Test coverage: 98.2%
-├── Type checking passed
-├── Linting passed
-├── CHANGELOG.md updated
-└── No critical issues open
-
-⚠️  WARNINGS:
-├── 2 medium-priority issues still open
-└── Documentation could be updated
-
-❌ BLOCKING ISSUES:
-└── None found
-
-🎯 RELEASE READINESS: ✅ READY
-
-Recommended next steps:
-1. Address warnings if desired
-2. Run `/release v0.13.0` when ready
-```
-
-## Validation Criteria
-
-### Must Pass (Blocking)
-- [ ] All tests pass
-- [ ] No type errors
-- [ ] No linting errors  
-- [ ] Working directory clean
-- [ ] On main branch
-- [ ] CHANGELOG.md has version entry
-- [ ] No critical open issues
-
-### Should Pass (Warnings)
-- [ ] Test coverage >95%
-- [ ] No medium-priority open issues
-- [ ] Documentation up to date
-- [ ] No dependency vulnerabilities
-
-## Context
-- This is a read-only validation - makes no changes
-- Provides confidence before running actual release
-- Helps identify issues early in release process
-- Can be run multiple times safely

.claude/commands/release/release.md

@@ -1,92 +0,0 @@
-# /release - Create Stable Release
-
-Create a stable release using the automated justfile target with comprehensive validation.
-
-## Usage
-```
-/release <version>
-```
-
-**Parameters:**
-- `version` (required): Release version like `v0.13.2`
-
-## Implementation
-
-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
-
-#### Documentation Validation
-1. **Changelog Check**
-   - CHANGELOG.md contains entry for target version
-   - Entry includes all major features and fixes
-   - Breaking changes are documented
-
-### Step 2: Use Justfile Automation
-Execute the automated release process:
-```bash
-just release <version>
-```
-
-The justfile target handles:
-- ✅ Version format validation
-- ✅ Git status and branch checks
-- ✅ Quality checks (`just check` - lint, format, type-check, tests)
-- ✅ Version update in `src/basic_memory/__init__.py`
-- ✅ Automatic commit with proper message
-- ✅ Tag creation and pushing to GitHub
-- ✅ Release workflow trigger
-
-### 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`
-
-### 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
-
-## Pre-conditions Check
-Before starting, verify:
-- [ ] All beta testing is complete
-- [ ] Critical bugs are fixed
-- [ ] Breaking changes are documented
-- [ ] CHANGELOG.md is updated (if needed)
-- [ ] Version number follows semantic versioning
-
-## Error Handling
-- If `just release` fails, examine the error output for specific issues
-- If quality checks fail, fix issues and retry
-- If changelog entry missing, update CHANGELOG.md and commit before retrying
-- If GitHub Actions fail, check workflow logs for debugging
-
-## Success Output
-```
-🎉 Stable Release v0.13.2 Created Successfully!
-
-🏷️  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/
-🚀 GitHub Actions: Completed
-
-Install with:
-uv tool install basic-memory
-
-Users can now upgrade:
-uv tool 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`
-- Triggers automated GitHub release with changelog
-- Leverages uv-dynamic-versioning for package version management

.claude/commands/spec.md

@@ -1,55 +0,0 @@
----
-allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__read_note, mcp__basic-memory__search_notes, mcp__basic-memory__edit_note, Task
-argument-hint: [create|status|implement|review] [spec-name]
-description: Manage specifications in our development process
----
-
-## Context
-
-You are managing specifications using our specification-driven development process defined in @docs/specs/SPEC-001.md.
-
-Available commands:
-- `create [name]` - Create new specification
-- `status` - Show all spec statuses
-- `implement [spec-name]` - Hand spec to appropriate agent
-- `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
-2. Create new spec using template from @docs/specs/Slash\ Commands\ Reference.md
-3. Place in `/specs` folder with title "SPEC-XXX: [name]"
-4. Include standard sections: Why, What, How, How to Evaluate
-
-### If command is "status":
-1. Search all notes in `/specs` folder
-2. Display table with spec number, title, and status
-3. Show any dependencies or assigned agents
-
-### If command is "implement":
-1. Read the specified spec
-2. Determine appropriate agent based on content:
-   - Frontend/UI → vue-developer
-   - Architecture/system → system-architect  
-   - Backend/API → python-developer
-3. Launch Task tool with appropriate agent and spec context
-
-### If command is "review":
-1. Read the specified spec and its "How to Evaluate" section
-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
-5. If gaps found, clearly identify what still needs to be implemented/tested
-
-Use the agent definitions from @docs/specs/Agent\ Definitions.md for implementation handoffs.

.claude/commands/test-live.md

@@ -1,622 +0,0 @@
-# /project:test-live - Live Basic Memory Testing Suite
-
-Execute comprehensive real-world testing of Basic Memory using the installed version. 
-All test results are recorded as notes in a dedicated test project.
-
-## Usage
-```
-/project:test-live [phase]
-```
-
-**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_memory_projects, recent_activity)
-- `features` - Core + important workflows (Tier 1 + Tier 2)
-- `all` - Comprehensive testing of all tools and scenarios
-
-## Implementation
-
-You are an expert QA engineer conducting live testing of Basic Memory. 
-When the user runs `/project:test-live`, execute comprehensive test plan:
-
-## Tool Testing Priority
-
-### **Tier 1: Critical Core (Always Test)**
-1. **write_note** - Foundation of all knowledge creation
-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 session guidance
-6. **recent_activity** - Project discovery mode and activity analysis
-
-### **Tier 2: Important Workflows (Usually Test)**
-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. **edit_note** (advanced modes) - Complex find/replace operations
-
-### **Tier 4: Specialized (Rarely Test)**
-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
-
-1. **Environment Verification**
-   - Verify basic-memory is installed and accessible via MCP
-   - Check version and confirm it's the expected release
-   - Test MCP connection and tool availability
-
-2. **Recent Changes Analysis** (if phase includes 'recent' or 'all')
-   - Run `git log --oneline -20` to examine recent commits
-   - Identify new features, bug fixes, and enhancements
-   - Generate targeted test scenarios for recent changes
-   - Prioritize regression testing for recently fixed issues
-
-3. **Test Project Creation**
-
-Run the bash `date` command to get the current date/time. 
-
-   ```
-   Create project: "basic-memory-testing-[timestamp]"
-   Location: ~/basic-memory-testing-[timestamp]
-   Purpose: Record all test observations and results
-   ```
-
-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:
-   - Test environment details
-   - Version being tested
-   - Recent changes identified (if applicable)
-   - Test objectives and scope
-   - Start timestamp
-
-### Phase 0: Recent Changes Validation (if 'recent' or 'all' phase)
-
-Based on recent commit analysis, create targeted test scenarios:
-
-**Recent Changes Test Protocol:**
-1. **Feature Addition Tests** - For each new feature identified:
-   - Test basic functionality
-   - Test integration with existing tools
-   - Verify documentation accuracy
-   - Test edge cases and error handling
-
-2. **Bug Fix Regression Tests** - For each recent fix:
-   - Recreate the original problem scenario
-   - Verify the fix works as expected
-   - Test related functionality isn't broken
-   - Document the verification in test notes
-
-3. **Performance/Enhancement Validation** - For optimizations:
-   - Establish baseline timing
-   - Compare with expected improvements
-   - Test under various load conditions
-   - Document performance observations
-
-**Example Recent Changes (Update based on actual git log):**
-- Watch Service Restart (#156): Test project creation → file modification → automatic restart
-- Cross-Project Moves (#161): Test move_note with cross-project detection
-- Docker Environment Support (#174): Test BASIC_MEMORY_HOME behavior
-- MCP Server Logging (#164): Verify log level configurations
-
-### Phase 1: Core Functionality Validation (Tier 1 Tools)
-
-Test essential MCP tools that form the foundation of Basic Memory:
-
-**1. write_note Tests (Critical):**
-- ✅ Basic note creation with frontmatter
-- ✅ Special characters and Unicode in titles
-- ✅ Various content types (lists, headings, code blocks)
-- ✅ Empty notes and minimal content edge cases
-- ⚠️ Error handling for invalid parameters
-
-**2. read_note Tests (Critical):**
-- ✅ Read by title, permalink, memory:// URLs
-- ✅ Non-existent notes (error handling)
-- ✅ Notes with complex markdown formatting
-- ⚠️ Performance with large notes (>10MB)
-
-**3. search_notes Tests (Critical):**
-- ✅ Simple text queries across content
-- ✅ Tag-based searches with multiple tags
-- ✅ Boolean operators (AND, OR, NOT)
-- ✅ Empty/no results scenarios
-- ⚠️ Performance with 100+ notes
-
-**4. edit_note Tests (Critical):**
-- ✅ Append operations preserving frontmatter
-- ✅ Prepend operations
-- ✅ Find/replace with validation
-- ✅ Section replacement under headers
-- ⚠️ Error scenarios (invalid operations)
-
-**5. list_memory_projects Tests (Critical):**
-- ✅ Display all projects with clear session guidance
-- ✅ Project discovery workflow prompts
-- ✅ Removal of CLI-specific references
-- ✅ Empty project list handling
-- ✅ Single project constraint mode display
-
-**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. build_context Tests (Important):**
-- ✅ Different depth levels (1, 2, 3+)
-- ✅ Various timeframes for context
-- ✅ memory:// URL navigation
-- ⚠️ Performance with complex relation graphs
-
-**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
-
-**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
-
-**10. sync_status Tests (Important):**
-- ✅ Background operation monitoring
-- ✅ File synchronization status
-- ✅ Project sync state reporting
-- ⚠️ Error state handling
-
-### Phase 3: Enhanced Functionality (Tier 3 Tools)
-
-**11. view_note Tests (Enhanced):**
-- ✅ Claude Desktop artifact display
-- ✅ Title extraction from frontmatter
-- ✅ Unicode and emoji content rendering
-- ⚠️ Error handling for non-existent notes
-
-**12. read_content Tests (Enhanced):**
-- ✅ Raw file content access
-- ✅ Binary file handling
-- ✅ Image file reading
-- ⚠️ Large file performance
-
-**13. delete_note Tests (Enhanced):**
-- ✅ Single note deletion
-- ✅ Database consistency after deletion
-- ⚠️ Non-existent note handling
-- ✅ Confirmation of successful deletion
-
-**14. list_directory Tests (Enhanced):**
-- ✅ Directory content listing
-- ✅ Depth control and filtering
-- ✅ File name globbing
-- ⚠️ Empty directory handling
-
-**15. delete_project Tests (Enhanced):**
-- ✅ Project removal from config
-- ✅ Database cleanup
-- ⚠️ Default project protection
-- ⚠️ Non-existent project handling
-
-### Phase 4: Edge Case Exploration
-
-**Boundary Testing:**
-- Very long titles and content (stress limits)
-- Empty projects and notes
-- Unicode, emojis, special symbols
-- Deeply nested folder structures
-- Circular relations and self-references
-- Maximum relation depths
-
-**Error Scenarios:**
-- Invalid memory:// URLs
-- Missing files referenced in database
-- Invalid project names and paths
-- Malformed note structures
-- Concurrent operation conflicts
-
-**Performance Testing:**
-- Create 100+ notes rapidly
-- Complex search queries
-- Deep relation chains (5+ levels)
-- Rapid successive operations
-- Memory usage monitoring
-
-### Phase 5: Real-World Workflow Scenarios
-
-**Meeting Notes Pipeline:**
-1. Create meeting notes with action items
-2. Extract action items using edit_note
-3. Build relations to project documents
-4. Update progress incrementally
-5. Search and track completion
-
-**Research Knowledge Building:**
-1. Create research topic hierarchy
-2. Build complex relation networks
-3. Add incremental findings over time
-4. Search for connections and patterns
-5. Reorganize as knowledge evolves
-
-**Multi-Project Workflow:**
-1. Technical documentation project
-2. Personal recipe collection project
-3. Learning/course notes project
-4. Specify different projects for different operations
-5. Cross-reference related concepts
-
-**Content Evolution:**
-1. Start with basic notes
-2. Enhance with relations and observations
-3. Reorganize file structure using moves
-4. Update content with edit operations
-5. Validate knowledge graph integrity
-
-### Phase 6: Specialized Tools Testing (Tier 4)
-
-**16. canvas Tests (Specialized):**
-- ✅ JSON Canvas generation
-- ✅ Node and edge creation
-- ✅ Obsidian compatibility
-- ⚠️ Complex graph handling
-
-**17. MCP Prompts Tests (Specialized):**
-- ✅ ai_assistant_guide output
-- ✅ continue_conversation functionality
-- ✅ Formatted search results
-- ✅ Enhanced activity reports
-
-### Phase 7: Integration & File Watching Tests
-
-**File System Integration:**
-- ✅ Watch service behavior with file changes
-- ✅ Project creation → watch restart (#156)
-- ✅ Multi-project synchronization
-- ⚠️ MCP→API→DB→File stack validation
-
-**Real Integration Testing:**
-- ✅ End-to-end file watching vs manual operations
-- ✅ Cross-session persistence
-- ✅ Database consistency across operations
-- ⚠️ Performance under real file system changes
-
-### Phase 8: Creative Stress Testing
-
-**Creative Exploration:**
-- Rapid project creation/switching patterns
-- Unusual but valid markdown structures
-- Creative observation categories
-- Novel relation types and patterns
-- Unexpected tool combinations
-
-**Stress Scenarios:**
-- Bulk operations (many notes quickly)
-- Complex nested moves and edits
-- Deep context building
-- Complex boolean search expressions
-- Resource constraint testing
-
-## Test Execution Guidelines
-
-### Quick Testing (core/features phases)
-- Focus on Tier 1 tools (core) or Tier 1+2 (features)
-- Test essential functionality and common edge cases
-- Record critical issues immediately
-- Complete in 15-20 minutes
-
-### Comprehensive Testing (all phase)
-- Cover all tiers systematically
-- Include specialized tools and stress testing
-- Document performance baselines
-- Complete in 45-60 minutes
-
-### Recent Changes Focus (recent phase)
-- Analyze git log for recent commits
-- Generate targeted test scenarios
-- Focus on regression testing for fixes
-- Validate new features thoroughly
-
-## Test Observation Format
-
-Record ALL observations immediately as Basic Memory notes:
-
-```markdown
----
-title: Test Session [Phase] YYYY-MM-DD HH:MM
-tags: [testing, v0.13.0, live-testing, [phase]]
-permalink: test-session-[phase]-[timestamp]
----
-
-# Test Session [Phase] - [Date/Time]
-
-## Environment
-- Basic Memory version: [version]
-- MCP connection: [status]
-- Test project: [name]
-- Phase focus: [description]
-
-## Test Results
-
-### ✅ Successful Operations
-- [timestamp] ✅ write_note: Created note with emoji title 📝 #tier1 #functionality
-- [timestamp] ✅ search_notes: Boolean query returned 23 results in 0.4s #tier1 #performance  
-- [timestamp] ✅ edit_note: Append operation preserved frontmatter #tier1 #reliability
-
-### ⚠️ Issues Discovered
-- [timestamp] ⚠️ move_note: Slow with deep folder paths (2.1s) #tier2 #performance
-- [timestamp] 🚨 search_notes: Unicode query returned unexpected results #tier1 #bug #critical
-- [timestamp] ⚠️ build_context: Context lost for memory:// URLs #tier2 #issue
-
-### 🚀 Enhancements Identified
-- edit_note could benefit from preview mode #ux-improvement
-- search_notes needs fuzzy matching for typos #feature-idea
-- move_note could auto-suggest folder creation #usability
-
-### 📊 Performance Metrics
-- Average write_note time: 0.3s
-- Search with 100+ notes: 0.6s
-- Project parameter overhead: <0.1s
-- Memory usage: [observed levels]
-
-## Relations
-- tests [[Basic Memory v0.13.0]]
-- part_of [[Live Testing Suite]]
-- found_issues [[Bug Report: Unicode Search]]
-- discovered [[Performance Optimization Opportunities]]
-```
-
-## Quality Assessment Areas
-
-**User Experience & Usability:**
-- Tool instruction clarity and examples
-- Error message actionability
-- Response time acceptability
-- Tool consistency and discoverability
-- Learning curve and intuitiveness
-
-**System Behavior:**
-- Stateless operation independence
-- memory:// URL navigation reliability
-- Multi-step workflow cohesion
-- Edge case graceful handling
-- Recovery from user errors
-
-**Documentation Alignment:**
-- Tool output clarity and helpfulness
-- Behavior vs. documentation accuracy
-- Example validity and usefulness
-- Real-world vs. documented workflows
-
-**Mental Model Validation:**
-- Natural user expectation alignment
-- Surprising behavior identification
-- Mistake recovery ease
-- Knowledge graph concept naturalness
-
-**Performance & Reliability:**
-- Operation completion times
-- Consistency across sessions
-- Scaling behavior with growth
-- Unexpected slowness identification
-
-## Error Documentation Protocol
-
-For each error discovered:
-
-1. **Immediate Recording**
-   - Create dedicated error note
-   - Include exact reproduction steps
-   - Capture error messages verbatim
-   - Note system state when error occurred
-
-2. **Error Note Format**
-   ```markdown
-   ---
-   title: Bug Report - [Short Description]
-   tags: [bug, testing, v0.13.0, [severity]]
-   ---
-   
-   # Bug Report: [Description]
-   
-   ## Reproduction Steps
-   1. [Exact steps to reproduce]
-   2. [Include all parameters used]
-   3. [Note any special conditions]
-   
-   ## Expected Behavior
-   [What should have happened]
-   
-   ## Actual Behavior  
-   [What actually happened]
-   
-   ## Error Messages
-   ```
-   [Exact error text]
-   ```
-   
-   ## Environment
-   - Version: [version]
-   - Project: [name]
-   - Timestamp: [when]
-   
-   ## Severity
-   - [ ] Critical (blocks major functionality)
-   - [ ] High (impacts user experience)
-   - [ ] Medium (workaround available)
-   - [ ] Low (minor inconvenience)
-   
-   ## Relations
-   - discovered_during [[Test Session [Phase]]]
-   - affects [[Feature Name]]
-   ```
-
-## Success Metrics Tracking
-
-**Quantitative Measures:**
-- Test scenario completion rate
-- Bug discovery count with severity
-- Performance benchmark establishment
-- Tool coverage completeness
-
-**Qualitative Measures:**
-- Conversation flow naturalness
-- Knowledge graph quality
-- User experience insights
-- System reliability assessment
-
-## Test Execution Flow
-
-1. **Setup Phase** (5 minutes)
-   - Verify environment and create test project
-   - Record baseline system state
-   - Establish performance benchmarks
-
-2. **Core Testing** (15-20 minutes per phase)
-   - Execute test scenarios systematically
-   - Record observations immediately
-   - Note timestamps for performance tracking
-   - Explore variations when interesting behaviors occur
-
-3. **Documentation** (5 minutes per phase)
-   - Create phase summary note
-   - Link related test observations
-   - Update running issues list
-   - Record enhancement ideas
-
-4. **Analysis Phase** (10 minutes)
-   - Review all observations across phases
-   - Identify patterns and trends
-   - Create comprehensive summary report
-   - Generate development recommendations
-
-## Testing Success Criteria
-
-### Core Testing (Tier 1) - Must Pass
-- All 6 critical tools function correctly
-- No critical bugs in essential workflows
-- Acceptable performance for basic operations
-- Error handling works as expected
-
-### Feature Testing (Tier 1+2) - Should Pass
-- All 11 core + important tools function
-- Workflow scenarios complete successfully
-- Performance meets baseline expectations
-- Integration points work correctly
-
-### Comprehensive Testing (All Tiers) - Complete Coverage
-- All tools tested across all scenarios
-- Edge cases and stress testing completed
-- Performance baselines established
-- Full documentation of issues and enhancements
-
-## Expected Outcomes
-
-**System Validation:**
-- Feature verification prioritized by tier importance
-- Recent changes validated for regression
-- Performance baseline establishment
-- Bug identification with severity assessment
-
-**Knowledge Base Creation:**
-- Prioritized testing documentation
-- Real usage examples for user guides
-- Recent changes validation records
-- Performance insights for optimization
-
-**Development Insights:**
-- Tier-based bug priority list
-- Recent changes impact assessment
-- Enhancement ideas from real usage
-- User experience improvement areas
-
-## Post-Test Deliverables
-
-1. **Test Summary Note**
-   - Overall results and findings
-   - Critical issues requiring immediate attention
-   - Enhancement opportunities discovered
-   - System readiness assessment
-
-2. **Bug Report Collection**
-   - All discovered issues with reproduction steps
-   - Severity and impact assessments
-   - Suggested fixes where applicable
-
-3. **Performance Baseline**
-   - Timing data for all operations
-   - Scaling behavior observations
-   - Resource usage patterns
-
-4. **UX Improvement Recommendations**
-   - Usability enhancement suggestions
-   - Documentation improvement areas
-   - Tool design optimization ideas
-
-5. **Updated TESTING.md**
-   - Incorporate new test scenarios discovered
-   - Update based on real execution experience
-   - Add performance benchmarks and targets
-
-## Context
-- Uses real installed basic-memory version 
-- Tests complete MCP→API→DB→File stack
-- Creates living documentation in Basic Memory itself
-- Follows integration over isolation philosophy
-- Prioritizes testing by tool importance and usage frequency
-- Adapts to recent development changes dynamically
-- Focuses on real usage patterns over checklist validation
-- Generates actionable insights prioritized by impact

.dockerignore

@@ -1,60 +0,0 @@
-# Git files
-.git/
-.gitignore
-.gitattributes
-
-# Development files
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# Testing files
-tests/
-test-int/
-.pytest_cache/
-.coverage
-htmlcov/
-
-# Build artifacts
-build/
-dist/
-*.egg-info/
-__pycache__/
-*.pyc
-*.pyo
-*.pyd
-.Python
-
-# Virtual environments (uv creates these during build)
-.venv/
-venv/
-.env
-
-# CI/CD files
-.github/
-
-# Documentation (keep README.md and pyproject.toml)
-docs/
-CHANGELOG.md
-CLAUDE.md
-CONTRIBUTING.md
-
-# Example files not needed for runtime
-examples/
-
-# Local development files
-.basic-memory/
-*.db
-*.sqlite3
-
-# OS files
-.DS_Store
-Thumbs.db
-
-# Temporary files
-tmp/
-temp/
-*.tmp
-*.log

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,38 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve Basic Memory
-title: '[BUG] '
-labels: bug
-assignees: ''
----
-
-## Bug Description
-A clear and concise description of what the bug is.
-
-## Steps To Reproduce
-Steps to reproduce the behavior:
-1. Install version '...'
-2. Run command '...'
-3. Use tool/feature '...'
-4. See error
-
-## Expected Behavior
-A clear and concise description of what you expected to happen.
-
-## Actual Behavior
-What actually happened, including error messages and output.
-
-## Environment
-- OS: [e.g. macOS 14.2, Ubuntu 22.04]
-- Python version: [e.g. 3.12.1]
-- Basic Memory version: [e.g. 0.1.0]
-- Installation method: [e.g. pip, uv, source]
-- Claude Desktop version (if applicable):
-
-## Additional Context
-- Configuration files (if relevant)
-- Logs or screenshots
-- Any special configuration or environment variables
-
-## Possible Solution
-If you have any ideas on what might be causing the issue or how to fix it, please share them here.

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +0,0 @@
-blank_issues_enabled: false
-contact_links:
-  - name: Basic Memory Discussions
-    url: https://github.com/basicmachines-co/basic-memory/discussions
-    about: For questions, ideas, or more open-ended discussions
-  - name: Documentation
-    url: https://github.com/basicmachines-co/basic-memory#readme
-    about: Please check the documentation first before reporting an issue

.github/ISSUE_TEMPLATE/documentation.md

@@ -1,19 +0,0 @@
----
-name: Documentation improvement
-about: Suggest improvements or report issues with documentation
-title: '[DOCS] '
-labels: documentation
-assignees: ''
----
-
-## Documentation Issue
-Describe what's missing, unclear, or incorrect in the current documentation.
-
-## Location
-Where is the problematic documentation? (URL, file path, or section)
-
-## Suggested Improvement
-How would you improve this documentation? Please be as specific as possible.
-
-## Additional Context
-Any additional information or screenshots that might help explain the issue or improvement.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,28 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for Basic Memory
-title: '[FEATURE] '
-labels: enhancement
-assignees: ''
----
-
-## Feature Description
-A clear and concise description of the feature you'd like to see implemented.
-
-## Problem This Feature Solves
-Describe the problem or limitation you're experiencing that this feature would address.
-
-## Proposed Solution
-Describe how you envision this feature working. Include:
-- User workflow
-- Interface design (if applicable)
-- Technical approach (if you have ideas)
-
-## Alternative Solutions
-Have you considered any alternative solutions or workarounds?
-
-## Additional Context
-Add any other context, screenshots, or examples about the feature request here.
-
-## Impact
-How would this feature benefit you and other users of Basic Memory?

.github/dependabot.yml

@@ -1,12 +0,0 @@
-# To get started with Dependabot version updates, you'll need to specify which
-# package ecosystems to update and where the package manifests are located.
-# Please see the documentation for all configuration options:
-# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
-
-version: 2
-updates:
-  - package-ecosystem: "" # See documentation for possible values
-    directory: "/" # Location of package manifests
-    schedule:
-      interval: "weekly"
-      

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

@@ -1,79 +0,0 @@
-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
-            - [ ] 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
-
-            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

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

@@ -1,68 +0,0 @@
-name: Claude Code
-
-on:
-  issue_comment:
-    types: [created]
-  pull_request_review_comment:
-    types: [created]
-  issues:
-    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 == '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: Checkout repository
-        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
-        id: claude
-        uses: anthropics/claude-code-action@v1
-        with:
-          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/dev-release.yml

@@ -1,53 +0,0 @@
-name: Dev Release
-
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:  # Allow manual triggering
-
-jobs:
-  dev-release:
-    runs-on: ubuntu-latest
-    permissions:
-      id-token: write
-      contents: write
-
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install uv
-        run: |
-          pip install uv
-
-      - name: Install dependencies and build
-        run: |
-          uv venv
-          uv sync
-          uv build
-
-      - name: Check if this is a dev version
-        id: check_version
-        run: |
-          VERSION=$(uv run python -c "import basic_memory; print(basic_memory.__version__)")
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          if [[ "$VERSION" == *"dev"* ]]; then
-            echo "is_dev=true" >> $GITHUB_OUTPUT
-            echo "Dev version detected: $VERSION"
-          else
-            echo "is_dev=false" >> $GITHUB_OUTPUT
-            echo "Release version detected: $VERSION, skipping dev release"
-          fi
-
-      - name: Publish dev version to PyPI
-        if: steps.check_version.outputs.is_dev == 'true'
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          password: ${{ secrets.PYPI_TOKEN }}
-          skip-existing: true  # Don't fail if version already exists

.github/workflows/docker.yml

@@ -1,61 +0,0 @@
-name: Docker Image CI
-
-on:
-  push:
-    tags:
-      - 'v*'  # Trigger on version tags like v1.0.0, v0.13.0, etc.
-  workflow_dispatch:  # Allow manual triggering for testing
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: basicmachines-co/basic-memory
-
-jobs:
-  docker:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-        with:
-          platforms: linux/amd64,linux/arm64
-
-      - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=ref,event=branch
-            type=ref,event=pr
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=raw,value=latest,enable={{is_default_branch}}
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          file: ./Dockerfile
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-

.github/workflows/pr-title.yml

@@ -1,41 +0,0 @@
-name: "Pull Request Title"
-
-on:
-  pull_request:
-    types:
-      - opened
-      - edited
-      - synchronize
-
-jobs:
-  main:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: amannn/action-semantic-pull-request@v5
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          # Configure allowed types based on what we want in our changelog
-          types: |
-            feat
-            fix
-            chore
-            docs
-            style
-            refactor
-            perf
-            test
-            build
-            ci
-          # Require at least one from scope list (optional)
-          scopes: |
-            core
-            cli
-            api
-            mcp
-            sync
-            ui
-            deps
-            installer
-          # Allow breaking changes (needs "!" after type/scope)
-          requireScopeForBreakingChange: true

.github/workflows/release.yml

@@ -1,85 +0,0 @@
-name: Release
-
-on:
-  push:
-    tags:
-      - 'v*'  # Trigger on version tags like v1.0.0, v0.13.0, etc.
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    permissions:
-      id-token: write
-      contents: write
-
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - name: Install uv
-        run: |
-          pip install uv
-
-      - name: Install dependencies and build
-        run: |
-          uv venv
-          uv sync
-          uv build
-
-      - name: Verify build succeeded
-        run: |
-          # Verify that build artifacts exist
-          ls -la dist/
-          echo "Build completed successfully"
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          files: |
-            dist/*.whl
-            dist/*.tar.gz
-          generate_release_notes: true
-          tag_name: ${{ github.ref_name }}
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          password: ${{ secrets.PYPI_TOKEN }}
-
-  homebrew:
-    name: Update Homebrew Formula
-    needs: release
-    runs-on: ubuntu-latest
-    # Only run for stable releases (not dev, beta, or rc versions)
-    if: ${{ !contains(github.ref_name, 'dev') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc') }}
-    permissions:
-      contents: write
-      actions: read
-    steps:
-      - name: Update Homebrew formula
-        uses: mislav/bump-homebrew-formula-action@v3
-        with:
-          # Formula name in homebrew-basic-memory repo
-          formula-name: basic-memory
-          # The tap repository
-          homebrew-tap: basicmachines-co/homebrew-basic-memory
-          # Base branch of the tap repository
-          base-branch: main
-          # Download URL will be automatically constructed from the tag
-          download-url: https://github.com/basicmachines-co/basic-memory/archive/refs/tags/${{ github.ref_name }}.tar.gz
-          # Commit message for the formula update
-          commit-message: |
-            {{formulaName}} {{version}}
-
-            Created by https://github.com/basicmachines-co/basic-memory/actions/runs/${{ github.run_id }}
-        env:
-          # Personal Access Token with repo scope for homebrew-basic-memory repo
-          COMMITTER_TOKEN: ${{ secrets.HOMEBREW_TOKEN }}
-

.github/workflows/test.yml

@@ -1,70 +0,0 @@
-name: Tests
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-  # pull_request_target runs on the BASE of the PR, not the merge result.
-  # It has write permissions and access to secrets.
-  # It's useful for PRs from forks or automated PRs but requires careful use for security reasons.
-  # See: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
-  pull_request_target:
-    branches: [ "main" ]
-
-jobs:
-  test:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest]
-        python-version: [ "3.12", "3.13" ]
-    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
-        run: |
-          uv pip install pytest pytest-cov
-          just test

.gitignore

@@ -1,55 +0,0 @@
-*.py[cod]
-__pycache__/
-.pytest_cache/
-.coverage
-htmlcov/
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-
-# Installer artifacts
-installer/build/
-installer/dist/
-rw.*.dmg  # Temporary disk images
-
-# Virtual environments
-.env
-.venv
-env/
-venv/
-ENV/
-
-# IDE
-.idea/
-.vscode/
-*.swp
-*.swo
-
-# macOS
-.DS_Store
-.coverage.*
-
-# obsidian docs:
-/docs/.obsidian/
-/examples/.obsidian/
-/examples/.basic-memory/
-
-
-# claude action
-claude-output
-**/.claude/settings.local.json

.python-version

@@ -1 +0,0 @@
-3.12

CITATION.cff

@@ -1,10 +0,0 @@
-cff-version: 1.0.3
-message: "If you use this project, please cite it as follows:"
-authors:
-  - family-names: "Hernandez"
-    given-names: "Paul"
-    affiliation: "Basic Machines"
-title: "Basic Memory"
-version: "0.0.1"
-date-released: "2025-02-03"
-url: "https://github.com/basicmachines-co/basic-memory"

CLA.md

@@ -1,71 +0,0 @@
-# Contributor License Agreement
-
-## Copyright Assignment and License Grant
-
-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.
-
-### 1. Definitions
-
-"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.
-
-"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").
-
-### 2. Grant of Copyright 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 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.
-
-### 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

@@ -1,268 +0,0 @@
-# CLAUDE.md - Basic Memory Project Guide
-
-## Project Overview
-
-Basic Memory is a local-first knowledge management system built on the Model Context Protocol (MCP). It enables
-bidirectional communication between LLMs (like Claude) and markdown files, creating a personal knowledge graph that can
-be traversed using links between documents.
-
-## CODEBASE DEVELOPMENT
-
-### Project information
-
-See the [README.md](README.md) file for a project overview.
-
-### Build and Test Commands
-
-- Install: `just install` or `pip install -e ".[dev]"`
-- Run all tests (with coverage): `just test` - Runs both unit and integration tests with unified coverage
-- Run unit tests only: `just test-unit` - Fast, no coverage
-- Run integration tests only: `just test-int` - Fast, no coverage
-- Generate HTML coverage: `just coverage` - Opens in browser
-- Single test: `pytest tests/path/to/test_file.py::test_function_name`
-- Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`
-- Lint: `just lint` or `ruff check . --fix`
-- Type check: `just typecheck` or `uv run pyright`
-- Format: `just format` or `uv run ruff format .`
-- Run all code checks: `just check` (runs lint, format, typecheck, test)
-- Create db migration: `just migration "Your migration message"`
-- Run development MCP Inspector: `just run-inspector`
-
-**Note:** Project requires Python 3.12+ (uses type parameter syntax and `type` aliases introduced in 3.12)
-
-### Test Structure
-
-- `tests/` - Unit tests for individual components (mocked, fast)
-- `test-int/` - Integration tests for real-world scenarios (no mocks, realistic)
-- Both directories are covered by unified coverage reporting
-- Benchmark tests in `test-int/` are marked with `@pytest.mark.benchmark`
-- Slow tests are marked with `@pytest.mark.slow`
-
-### Code Style Guidelines
-
-- Line length: 100 characters max
-- Python 3.12+ with full type annotations (uses type parameters and type aliases)
-- Format with ruff (consistent styling)
-- Import order: standard lib, third-party, local imports
-- Naming: snake_case for functions/variables, PascalCase for classes
-- Prefer async patterns with SQLAlchemy 2.0
-- Use Pydantic v2 for data validation and schemas
-- CLI uses Typer for command structure
-- API uses FastAPI for endpoints
-- Follow the repository pattern for data access
-- Tools communicate to api routers via the httpx ASGI client (in process)
-
-### Codebase Architecture
-
-- `/alembic` - Alembic db migrations
-- `/api` - FastAPI implementation of REST endpoints
-- `/cli` - Typer command-line interface
-- `/markdown` - Markdown parsing and processing
-- `/mcp` - Model Context Protocol server implementation
-- `/models` - SQLAlchemy ORM models
-- `/repository` - Data access layer
-- `/schemas` - Pydantic models for validation
-- `/services` - Business logic layer
-- `/sync` - File synchronization services
-
-### Development Notes
-
-- MCP tools are defined in src/basic_memory/mcp/tools/
-- MCP prompts are defined in src/basic_memory/mcp/prompts/
-- MCP tools should be atomic, composable operations
-- Use `textwrap.dedent()` for multi-line string formatting in prompts and tools
-- MCP Prompts are used to invoke tools and format content with instructions for an LLM
-- Schema changes require Alembic migrations
-- SQLite is used for indexing and full text search, files are source of truth
-- Testing uses pytest with asyncio support (strict mode)
-- Unit tests (`tests/`) use mocks when necessary; integration tests (`test-int/`) use real implementations
-- Test database uses in-memory SQLite
-- Each test runs in a standalone environment with in-memory SQLite and tmp_file directory
-- Performance benchmarks are in `test-int/test_sync_performance_benchmark.py`
-- Use pytest markers: `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests
-
-### Async Client Pattern (Important!)
-
-**All MCP tools and CLI commands use the context manager pattern for HTTP clients:**
-
-```python
-from basic_memory.mcp.async_client import get_client
-
-async def my_mcp_tool():
-    async with get_client() as client:
-        # Use client for API calls
-        response = await call_get(client, "/path")
-        return response
-```
-
-**Do NOT use:**
-- ❌ `from basic_memory.mcp.async_client import client` (deprecated module-level client)
-- ❌ Manual auth header management
-- ❌ `inject_auth_header()` (deleted)
-
-**Key principles:**
-- Auth happens at client creation, not per-request
-- Proper resource management via context managers
-- Supports three modes: Local (ASGI), CLI cloud (HTTP + auth), Cloud app (factory injection)
-- Factory pattern enables dependency injection for cloud consolidation
-
-**For cloud app integration:**
-```python
-from basic_memory.mcp import async_client
-
-# Set custom factory before importing tools
-async_client.set_client_factory(your_custom_factory)
-```
-
-See SPEC-16 for full context manager refactor details.
-
-## BASIC MEMORY PRODUCT USAGE
-
-### Knowledge Structure
-
-- Entity: Any concept, document, or idea represented as a markdown file
-- Observation: A categorized fact about an entity (`- [category] content`)
-- Relation: A directional link between entities (`- relation_type [[Target]]`)
-- Frontmatter: YAML metadata at the top of markdown files
-- Knowledge representation follows precise markdown format:
-    - Observations with [category] prefixes
-    - Relations with WikiLinks [[Entity]]
-    - Frontmatter with metadata
-
-### Basic Memory Commands
-
-**Local Commands:**
-- Sync knowledge: `basic-memory sync` or `basic-memory sync --watch`
-- Import from Claude: `basic-memory import claude conversations`
-- Import from ChatGPT: `basic-memory import chatgpt`
-- 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"`
-
-**Cloud Commands (requires subscription):**
-- Authenticate: `basic-memory cloud login`
-- Logout: `basic-memory cloud logout`
-- Bidirectional sync: `basic-memory cloud sync`
-- Integrity check: `basic-memory cloud check`
-- Mount cloud storage: `basic-memory cloud mount`
-- Unmount cloud storage: `basic-memory cloud unmount`
-
-### MCP Capabilities
-
-- Basic Memory exposes these MCP tools to LLMs:
-
-  **Content Management:**
-    - `write_note(title, content, folder, tags)` - Create/update markdown notes with semantic observations and relations
-    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph awareness
-    - `read_content(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
-    - `view_note(identifier, page, page_size)` - View notes as formatted artifacts for better readability
-    - `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, replace_section)
-    - `move_note(identifier, destination_path)` - Move notes to new locations, updating database and maintaining links
-    - `delete_note(identifier)` - Delete notes from the knowledge base
-
-  **Knowledge Graph Navigation:**
-    - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation continuity
-    - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "1d", "1 week")
-    - `list_directory(dir_name, depth, file_name_glob)` - Browse directory contents with filtering and depth control
-
-  **Search & Discovery:**
-    - `search_notes(query, page, page_size, search_type, types, entity_types, after_date)` - Full-text search across all content with advanced filtering options
-
-  **Project Management:**
-    - `list_memory_projects()` - List all available projects with their status
-    - `create_memory_project(project_name, project_path, set_default)` - Create new Basic Memory projects
-    - `delete_project(project_name)` - Delete a project from configuration
-    - `get_current_project()` - Get current project information and stats
-    - `sync_status()` - Check file synchronization and background operation status
-
-  **Visualization:**
-    - `canvas(nodes, edges, title, folder)` - Generate Obsidian canvas files for knowledge graph visualization
-
-- MCP Prompts for better AI interaction:
-    - `ai_assistant_guide()` - Guidance on effectively using Basic Memory tools for AI assistants
-    - `continue_conversation(topic, timeframe)` - Continue previous conversations with relevant historical context
-    - `search(query, after_date)` - Search with detailed, formatted results for better context understanding
-    - `recent_activity(timeframe)` - View recently changed items with formatted output
-    - `json_canvas_spec()` - Full JSON Canvas specification for Obsidian visualization
-
-### Cloud Features (v0.15.0+)
-
-Basic Memory now supports cloud synchronization and storage (requires active subscription):
-
-**Authentication:**
-- JWT-based authentication with subscription validation
-- Secure session management with token refresh
-- Support for multiple cloud projects
-
-**Bidirectional Sync:**
-- rclone bisync integration for two-way synchronization
-- Conflict resolution and integrity verification
-- Real-time sync with change detection
-- Mount/unmount cloud storage for direct file access
-
-**Cloud Project Management:**
-- Create and manage projects in the cloud
-- Toggle between local and cloud modes
-- Per-project sync configuration
-- Subscription-based access control
-
-**Security & Performance:**
-- Removed .env file loading for improved security
-- .gitignore integration (respects gitignored files)
-- WAL mode for SQLite performance
-- Background relation resolution (non-blocking startup)
-- API performance optimizations (SPEC-11)
-
-## AI-Human Collaborative Development
-
-Basic Memory emerged from and enables a new kind of development process that combines human and AI capabilities. Instead
-of using AI just for code generation, we've developed a true collaborative workflow:
-
-1. AI (LLM) writes initial implementation based on specifications and context
-2. Human reviews, runs tests, and commits code with any necessary adjustments
-3. Knowledge persists across conversations using Basic Memory's knowledge graph
-4. Development continues seamlessly across different AI sessions with consistent context
-5. Results improve through iterative collaboration and shared understanding
-
-This approach has allowed us to tackle more complex challenges and build a more robust system than either humans or AI
-could achieve independently.
-
-## GitHub Integration
-
-Basic Memory has taken AI-Human collaboration to the next level by integrating Claude directly into the development workflow through GitHub:
-
-### GitHub MCP Tools
-
-Using the GitHub Model Context Protocol server, Claude can now:
-
-- **Repository Management**:
-  - View repository files and structure
-  - Read file contents
-  - Create new branches
-  - Create and update files
-
-- **Issue Management**:
-  - Create new issues
-  - Comment on existing issues
-  - Close and update issues
-  - Search across issues
-
-- **Pull Request Workflow**:
-  - Create pull requests
-  - Review code changes
-  - Add comments to PRs
-
-This integration enables Claude to participate as a full team member in the development process, not just as a code generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic Machines organization with direct contributor access to the codebase.
-
-### Collaborative Development Process
-
-With GitHub integration, the development workflow includes:
-
-1. **Direct code review** - Claude can analyze PRs and provide detailed feedback
-2. **Contribution tracking** - All of Claude's contributions are properly attributed in the Git history
-3. **Branch management** - Claude can create feature branches for implementations
-4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
-
-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.

CODE_OF_CONDUCT.md

@@ -1,19 +0,0 @@
-# Code of Conduct
-
-## Purpose
-
-Maintain a respectful and professional environment where contributions can be made without harassment or
-negativity.
-
-## Standards
-
-Respectful communication and collaboration are expected. Offensive behavior, harassment, or personal attacks will not be
-tolerated.
-
-## Reporting Issues
-
-To report inappropriate behavior, contact [paul@basicmachines.co].
-
-## Consequences
-
-Violations of this code may lead to consequences, including being banned from contributing to the project.

CONTRIBUTING.md

@@ -1,277 +0,0 @@
-# Contributing to Basic Memory
-
-Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the
-project and how to get started as a developer.
-
-## Getting Started
-
-### Development Environment
-
-1. **Clone the Repository**:
-   ```bash
-   git clone https://github.com/basicmachines-co/basic-memory.git
-   cd basic-memory
-   ```
-
-2. **Install Dependencies**:
-   ```bash
-   # Using just (recommended)
-   just install
-   
-   # Or using uv
-   uv install -e ".[dev]"
-   
-   # Or using pip
-   pip install -e ".[dev]"
-   ```
-
-   > **Note**: Basic Memory uses [just](https://just.systems) as a modern command runner. Install with `brew install just` or `cargo install just`.
-
-3. **Activate the Virtual Environment**
-   ```bash
-   source .venv/bin/activate
-   ```
-
-4. **Run the Tests**:
-   ```bash
-   # Run all tests with unified coverage (unit + integration)
-   just test
-
-   # Run unit tests only (fast, no coverage)
-   just test-unit
-
-   # Run integration tests only (fast, no coverage)
-   just test-int
-
-   # Generate HTML coverage report
-   just coverage
-
-   # Run a specific test
-   pytest tests/path/to/test_file.py::test_function_name
-   ```
-
-### Development Workflow
-
-1. **Fork the Repo**: Fork the repository on GitHub and clone your copy.
-2. **Create a Branch**: Create a new branch for your feature or fix.
-   ```bash
-   git checkout -b feature/your-feature-name
-   # or
-   git checkout -b fix/issue-you-are-fixing
-   ```
-3. **Make Your Changes**: Implement your changes with appropriate test coverage.
-4. **Check Code Quality**:
-   ```bash
-   # Run all checks at once
-   just check
-   
-   # Or run individual checks
-   just lint      # Run linting
-   just format    # Format code
-   just type-check  # Type checking
-   ```
-5. **Test Your Changes**: Ensure all tests pass locally and maintain 100% test coverage.
-   ```bash
-   just test
-   ```
-6. **Submit a PR**: Submit a pull request with a detailed description of your changes.
-
-## LLM-Assisted Development
-
-This project is designed for collaborative development between humans and LLMs (Large Language Models):
-
-1. **CLAUDE.md**: The repository includes a `CLAUDE.md` file that serves as a project guide for both humans and LLMs.
-   This file contains:
-    - Key project information and architectural overview
-    - Development commands and workflows
-    - Code style guidelines
-    - Documentation standards
-
-2. **AI-Human Collaborative Workflow**:
-    - We encourage using LLMs like Claude for code generation, reviews, and documentation
-    - When possible, save context in markdown files that can be referenced later
-    - This enables seamless knowledge transfer between different development sessions
-    - Claude can help with implementation details while you focus on architecture and design
-
-3. **Adding to CLAUDE.md**:
-    - If you discover useful project information or common commands, consider adding them to CLAUDE.md
-    - This helps all contributors (human and AI) maintain consistent knowledge of the project
-
-## Pull Request Process
-
-1. **Create a Pull Request**: Open a PR against the `main` branch with a clear title and description.
-2. **Sign the Developer Certificate of Origin (DCO)**: All contributions require signing our DCO, which certifies that
-   you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you
-   create a PR.
-3. **PR Description**: Include:
-    - What the PR changes
-    - Why the change is needed
-    - How you tested the changes
-    - Any related issues (use "Fixes #123" to automatically close issues)
-4. **Code Review**: Wait for code review and address any feedback.
-5. **CI Checks**: Ensure all CI checks pass.
-6. **Merge**: Once approved, a maintainer will merge your PR.
-
-## Developer Certificate of Origin
-
-By contributing to this project, you agree to the [Developer Certificate of Origin (DCO)](CLA.md). This means you
-certify that:
-
-- You have the right to submit your contributions
-- You're not knowingly submitting code with patent or copyright issues
-- Your contributions are provided under the project's license (AGPL-3.0)
-
-This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be
-properly incorporated into the project and potentially used in commercial applications.
-
-### Signing Your Commits
-
-Sign your commit:
-
-**Using the `-s` or `--signoff` flag**:
-
-```bash
-git commit -s -m "Your commit message"
-```
-
-This adds a `Signed-off-by` line to your commit message, certifying that you adhere to the DCO.
-
-The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your
-agreement to the DCO.
-
-## Code Style Guidelines
-
-- **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
-- **Naming**: Use snake_case for functions/variables, PascalCase for classes
-- **Documentation**: Add docstrings to public functions, classes, and methods
-- **Type Annotations**: Use type hints for all functions and methods
-
-## Testing Guidelines
-
-### Test Structure
-
-Basic Memory uses two test directories with unified coverage reporting:
-
-- **`tests/`**: Unit tests that test individual components in isolation
-  - Fast execution with extensive mocking
-  - Test individual functions, classes, and modules
-  - Run with: `just test-unit` (no coverage, fast)
-
-- **`test-int/`**: Integration tests that test real-world scenarios
-  - Test full workflows with real database and file operations
-  - Include performance benchmarks
-  - More realistic but slower than unit tests
-  - Run with: `just test-int` (no coverage, fast)
-
-### Running Tests
-
-```bash
-# Run all tests with unified coverage report
-just test
-
-# Run only unit tests (fast iteration)
-just test-unit
-
-# Run only integration tests
-just test-int
-
-# Generate HTML coverage report
-just coverage
-
-# Run specific test
-pytest tests/path/to/test_file.py::test_function_name
-
-# Run tests excluding benchmarks
-pytest -m "not benchmark"
-
-# Run only benchmark tests
-pytest -m benchmark test-int/test_sync_performance_benchmark.py
-```
-
-### Performance Benchmarks
-
-The `test-int/test_sync_performance_benchmark.py` file contains performance benchmarks that measure sync and indexing speed:
-
-- `test_benchmark_sync_100_files` - Small repository performance
-- `test_benchmark_sync_500_files` - Medium repository performance
-- `test_benchmark_sync_1000_files` - Large repository performance (marked slow)
-- `test_benchmark_resync_no_changes` - Re-sync performance baseline
-
-Run benchmarks with:
-```bash
-# Run all benchmarks (excluding slow ones)
-pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"
-
-# Run all benchmarks including slow ones
-pytest test-int/test_sync_performance_benchmark.py -v -m benchmark
-
-# Run specific benchmark
-pytest test-int/test_sync_performance_benchmark.py::test_benchmark_sync_100_files -v
-```
-
-See `test-int/BENCHMARKS.md` for detailed benchmark documentation.
-
-### Testing Best Practices
-
-- **Coverage Target**: We aim for high test coverage for all code
-- **Test Framework**: Use pytest for unit and integration tests
-- **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
-
-Basic Memory uses automatic versioning based on git tags with `uv-dynamic-versioning`. Here's how releases work:
-
-### Version Management
-- **Development versions**: Automatically generated from git commits (e.g., `0.12.4.dev26+468a22f`)
-- **Beta releases**: Created by tagging with beta suffixes (e.g., `git tag v0.13.0b1`)
-- **Stable releases**: Created by tagging with version numbers (e.g., `git tag v0.13.0`)
-
-### Release Workflows
-
-#### Development Builds
-- Automatically published to PyPI on every commit to `main`
-- Version format: `0.12.4.dev26+468a22f` (base version + dev + commit count + hash)
-- Users install with: `pip install basic-memory --pre --force-reinstall`
-
-#### Beta Releases
-1. Create and push a beta tag: `git tag v0.13.0b1 && git push origin v0.13.0b1`
-2. GitHub Actions automatically builds and publishes to PyPI
-3. Users install with: `pip install basic-memory --pre`
-
-#### Stable Releases
-1. Create and push a version tag: `git tag v0.13.0 && git push origin v0.13.0`
-2. GitHub Actions automatically:
-   - Builds the package with version `0.13.0`
-   - Creates GitHub release with auto-generated notes
-   - Publishes to PyPI
-3. Users install with: `pip install basic-memory`
-
-### For Contributors
-- No manual version bumping required
-- Versions are automatically derived from git tags
-- Focus on code changes, not version management
-
-## Creating Issues
-
-If you're planning to work on something, please create an issue first to discuss the approach. Include:
-
-- A clear title and description
-- Steps to reproduce if reporting a bug
-- Expected behavior vs. actual behavior
-- Any relevant logs or screenshots
-- Your proposed solution, if you have one
-
-## Code of Conduct
-
-All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md).
-
-## Thank You!
-
-Your contributions help make Basic Memory better. We appreciate your time and effort!

Dockerfile

@@ -1,46 +0,0 @@
-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
-ENV PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1
-
-# 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
-WORKDIR /app
-RUN uv sync --locked
-
-# 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/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
-
-# Health check
-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"]

LICENSE

@@ -1,661 +0,0 @@
-                    GNU AFFERO GENERAL PUBLIC LICENSE
-                       Version 3, 19 November 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                            Preamble
-
-  The GNU Affero General Public License is a free, copyleft license for
-software and other kinds of works, specifically designed to ensure
-cooperation with the community in the case of network server software.
-
-  The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works.  By contrast,
-our General Public Licenses are intended to guarantee your freedom to
-share and change all versions of a program--to make sure it remains free
-software for all its users.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-  Developers that use our General Public Licenses protect your rights
-with two steps: (1) assert copyright on the software, and (2) offer
-you this License which gives you legal permission to copy, distribute
-and/or modify the software.
-
-  A secondary benefit of defending all users' freedom is that
-improvements made in alternate versions of the program, if they
-receive widespread use, become available for other developers to
-incorporate.  Many developers of free software are heartened and
-encouraged by the resulting cooperation.  However, in the case of
-software used on network servers, this result may fail to come about.
-The GNU General Public License permits making a modified version and
-letting the public access it on a server without ever releasing its
-source code to the public.
-
-  The GNU Affero General Public License is designed specifically to
-ensure that, in such cases, the modified source code becomes available
-to the community.  It requires the operator of a network server to
-provide the source code of the modified version running there to the
-users of that server.  Therefore, public use of a modified version, on
-a publicly accessible server, gives the public access to the source
-code of the modified version.
-
-  An older license, called the Affero General Public License and
-published by Affero, was designed to accomplish similar goals.  This is
-a different license, not a version of the Affero GPL, but Affero has
-released a new version of the Affero GPL which permits relicensing under
-this license.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                       TERMS AND CONDITIONS
-
-  0. Definitions.
-
-  "This License" refers to version 3 of the GNU Affero General Public License.
-
-  "Copyright" also means copyright-like laws that apply to other kinds of
-works, such as semiconductor masks.
-
-  "The Program" refers to any copyrightable work licensed under this
-License.  Each licensee is addressed as "you".  "Licensees" and
-"recipients" may be individuals or organizations.
-
-  To "modify" a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of an
-exact copy.  The resulting work is called a "modified version" of the
-earlier work or a work "based on" the earlier work.
-
-  A "covered work" means either the unmodified Program or a work based
-on the Program.
-
-  To "propagate" a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy.  Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-  To "convey" a work means any kind of propagation that enables other
-parties to make or receive copies.  Mere interaction with a user through
-a computer network, with no transfer of a copy, is not conveying.
-
-  An interactive user interface displays "Appropriate Legal Notices"
-to the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License.  If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-  1. Source Code.
-
-  The "source code" for a work means the preferred form of the work
-for making modifications to it.  "Object code" means any non-source
-form of a work.
-
-  A "Standard Interface" means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-  The "System Libraries" of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form.  A
-"Major Component", in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-  The "Corresponding Source" for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities.  However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work.  For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-  The Corresponding Source need not include anything that users
-can regenerate automatically from other parts of the Corresponding
-Source.
-
-  The Corresponding Source for a work in source code form is that
-same work.
-
-  2. Basic Permissions.
-
-  All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met.  This License explicitly affirms your unlimited
-permission to run the unmodified Program.  The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work.  This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-  You may make, run and propagate covered works that you do not
-convey, without conditions so long as your license otherwise remains
-in force.  You may convey covered works to others for the sole purpose
-of having them make modifications exclusively for you, or provide you
-with facilities for running those works, provided that you comply with
-the terms of this License in conveying all material for which you do
-not control copyright.  Those thus making or running the covered works
-for you must do so exclusively on your behalf, under your direction
-and control, on terms that prohibit them from making any copies of
-your copyrighted material outside their relationship with you.
-
-  Conveying under any other circumstances is permitted solely under
-the conditions stated below.  Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-  No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-  When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such circumvention
-is effected by exercising rights under this License with respect to
-the covered work, and you disclaim any intention to limit operation or
-modification of the work as a means of enforcing, against the work's
-users, your or third parties' legal rights to forbid circumvention of
-technological measures.
-
-  4. Conveying Verbatim Copies.
-
-  You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-  You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-  5. Conveying Modified Source Versions.
-
-  You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these conditions:
-
-    a) The work must carry prominent notices stating that you modified
-    it, and giving a relevant date.
-
-    b) The work must carry prominent notices stating that it is
-    released under this License and any conditions added under section
-    7.  This requirement modifies the requirement in section 4 to
-    "keep intact all notices".
-
-    c) You must license the entire work, as a whole, under this
-    License to anyone who comes into possession of a copy.  This
-    License will therefore apply, along with any applicable section 7
-    additional terms, to the whole of the work, and all its parts,
-    regardless of how they are packaged.  This License gives no
-    permission to license the work in any other way, but it does not
-    invalidate such permission if you have separately received it.
-
-    d) If the work has interactive user interfaces, each must display
-    Appropriate Legal Notices; however, if the Program has interactive
-    interfaces that do not display Appropriate Legal Notices, your
-    work need not make them do so.
-
-  A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-"aggregate" if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit.  Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-  6. Conveying Non-Source Forms.
-
-  You may convey a covered work in object code form under the terms
-of sections 4 and 5, provided that you also convey the
-machine-readable Corresponding Source under the terms of this License,
-in one of these ways:
-
-    a) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by the
-    Corresponding Source fixed on a durable physical medium
-    customarily used for software interchange.
-
-    b) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by a
-    written offer, valid for at least three years and valid for as
-    long as you offer spare parts or customer support for that product
-    model, to give anyone who possesses the object code either (1) a
-    copy of the Corresponding Source for all the software in the
-    product that is covered by this License, on a durable physical
-    medium customarily used for software interchange, for a price no
-    more than your reasonable cost of physically performing this
-    conveying of source, or (2) access to copy the
-    Corresponding Source from a network server at no charge.
-
-    c) Convey individual copies of the object code with a copy of the
-    written offer to provide the Corresponding Source.  This
-    alternative is allowed only occasionally and noncommercially, and
-    only if you received the object code with such an offer, in accord
-    with subsection 6b.
-
-    d) Convey the object code by offering access from a designated
-    place (gratis or for a charge), and offer equivalent access to the
-    Corresponding Source in the same way through the same place at no
-    further charge.  You need not require recipients to copy the
-    Corresponding Source along with the object code.  If the place to
-    copy the object code is a network server, the Corresponding Source
-    may be on a different server (operated by you or a third party)
-    that supports equivalent copying facilities, provided you maintain
-    clear directions next to the object code saying where to find the
-    Corresponding Source.  Regardless of what server hosts the
-    Corresponding Source, you remain obligated to ensure that it is
-    available for as long as needed to satisfy these requirements.
-
-    e) Convey the object code using peer-to-peer transmission, provided
-    you inform other peers where the object code and Corresponding
-    Source of the work are being offered to the general public at no
-    charge under subsection 6d.
-
-  A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-  A "User Product" is either (1) a "consumer product", which means any
-tangible personal property which is normally used for personal, family,
-or household purposes, or (2) anything designed or sold for incorporation
-into a dwelling.  In determining whether a product is a consumer product,
-doubtful cases shall be resolved in favor of coverage.  For a particular
-product received by a particular user, "normally used" refers to a
-typical or common use of that class of product, regardless of the status
-of the particular user or of the way in which the particular user
-actually uses, or expects or is expected to use, the product.  A product
-is a consumer product regardless of whether the product has substantial
-commercial, industrial or non-consumer uses, unless such uses represent
-the only significant mode of use of the product.
-
-  "Installation Information" for a User Product means any methods,
-procedures, authorization keys, or other information required to install
-and execute modified versions of a covered work in that User Product from
-a modified version of its Corresponding Source.  The information must
-suffice to ensure that the continued functioning of the modified object
-code is in no case prevented or interfered with solely because
-modification has been made.
-
-  If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information.  But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-  The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or updates
-for a work that has been modified or installed by the recipient, or for
-the User Product in which it has been modified or installed.  Access to a
-network may be denied when the modification itself materially and
-adversely affects the operation of the network or violates the rules and
-protocols for communication across the network.
-
-  Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-  7. Additional Terms.
-
-  "Additional permissions" are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law.  If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-  When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it.  (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.)  You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-  Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders of
-that material) supplement the terms of this License with terms:
-
-    a) Disclaiming warranty or limiting liability differently from the
-    terms of sections 15 and 16 of this License; or
-
-    b) Requiring preservation of specified reasonable legal notices or
-    author attributions in that material or in the Appropriate Legal
-    Notices displayed by works containing it; or
-
-    c) Prohibiting misrepresentation of the origin of that material, or
-    requiring that modified versions of such material be marked in
-    reasonable ways as different from the original version; or
-
-    d) Limiting the use for publicity purposes of names of licensors or
-    authors of the material; or
-
-    e) Declining to grant rights under trademark law for use of some
-    trade names, trademarks, or service marks; or
-
-    f) Requiring indemnification of licensors and authors of that
-    material by anyone who conveys the material (or modified versions of
-    it) with contractual assumptions of liability to the recipient, for
-    any liability that these contractual assumptions directly impose on
-    those licensors and authors.
-
-  All other non-permissive additional terms are considered "further
-restrictions" within the meaning of section 10.  If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term.  If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-  If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-  Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions;
-the above requirements apply either way.
-
-  8. Termination.
-
-  You may not propagate or modify a covered work except as expressly
-provided under this License.  Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-  However, if you cease all violation of this License, then your
-license from a particular copyright holder is reinstated (a)
-provisionally, unless and until the copyright holder explicitly and
-finally terminates your license, and (b) permanently, if the copyright
-holder fails to notify you of the violation by some reasonable means
-prior to 60 days after the cessation.
-
-  Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-  Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, you do not qualify to receive new licenses for the same
-material under section 10.
-
-  9. Acceptance Not Required for Having Copies.
-
-  You are not required to accept this License in order to receive or
-run a copy of the Program.  Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance.  However,
-nothing other than this License grants you permission to propagate or
-modify any covered work.  These actions infringe copyright if you do
-not accept this License.  Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-  10. Automatic Licensing of Downstream Recipients.
-
-  Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License.  You are not responsible
-for enforcing compliance by third parties with this License.
-
-  An "entity transaction" is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations.  If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-  You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License.  For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-  11. Patents.
-
-  A "contributor" is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based.  The
-work thus licensed is called the contributor's "contributor version".
-
-  A contributor's "essential patent claims" are all patent claims
-owned or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version.  For
-purposes of this definition, "control" includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-  Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-  In the following three paragraphs, a "patent license" is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement).  To "grant" such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-  If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients.  "Knowingly relying" means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-  If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-  A patent license is "discriminatory" if it does not include within
-the scope of its coverage, prohibits the exercise of, or is
-conditioned on the non-exercise of one or more of the rights that are
-specifically granted under this License.  You may not convey a covered
-work if you are a party to an arrangement with a third party that is
-in the business of distributing software, under which you make payment
-to the third party based on the extent of your activity of conveying
-the work, and under which the third party grants, to any of the
-parties who would receive the covered work from you, a discriminatory
-patent license (a) in connection with copies of the covered work
-conveyed by you (or copies made from those copies), or (b) primarily
-for and in connection with specific products or compilations that
-contain the covered work, unless you entered into that arrangement,
-or that patent license was granted, prior to 28 March 2007.
-
-  Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-  12. No Surrender of Others' Freedom.
-
-  If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot convey a
-covered work so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you may
-not convey it at all.  For example, if you agree to terms that obligate you
-to collect a royalty for further conveying from those to whom you convey
-the Program, the only way you could satisfy both those terms and this
-License would be to refrain entirely from conveying the Program.
-
-  13. Remote Network Interaction; Use with the GNU General Public License.
-
-  Notwithstanding any other provision of this License, if you modify the
-Program, your modified version must prominently offer all users
-interacting with it remotely through a computer network (if your version
-supports such interaction) an opportunity to receive the Corresponding
-Source of your version by providing access to the Corresponding Source
-from a network server at no charge, through some standard or customary
-means of facilitating copying of software.  This Corresponding Source
-shall include the Corresponding Source for any work covered by version 3
-of the GNU General Public License that is incorporated pursuant to the
-following paragraph.
-
-  Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU General Public License into a single
-combined work, and to convey the resulting work.  The terms of this
-License will continue to apply to the part which is the covered work,
-but the work with which it is combined will remain governed by version
-3 of the GNU General Public License.
-
-  14. Revised Versions of this License.
-
-  The Free Software Foundation may publish revised and/or new versions of
-the GNU Affero General Public License from time to time.  Such new versions
-will be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-  Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU Affero General
-Public License "or any later version" applies to it, you have the
-option of following the terms and conditions either of that numbered
-version or of any later version published by the Free Software
-Foundation.  If the Program does not specify a version number of the
-GNU Affero General Public License, you may choose any version ever published
-by the Free Software Foundation.
-
-  If the Program specifies that a proxy can decide which future
-versions of the GNU Affero General Public License can be used, that proxy's
-public statement of acceptance of a version permanently authorizes you
-to choose that version for the Program.
-
-  Later license versions may give you additional or different
-permissions.  However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-  15. Disclaimer of Warranty.
-
-  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
-OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
-IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
-ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  16. Limitation of Liability.
-
-  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
-USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
-DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
-EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGES.
-
-  17. Interpretation of Sections 15 and 16.
-
-  If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-                     END OF TERMS AND CONDITIONS
-
-            How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU Affero General Public License as published
-    by the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU Affero General Public License for more details.
-
-    You should have received a copy of the GNU Affero General Public License
-    along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper mail.
-
-  If your software can interact with users remotely through a computer
-network, you should also make sure that it provides a way for users to
-get its source.  For example, if your program is a web application, its
-interface could display a "Source" link that leads users to an archive
-of the code.  There are many ways you could offer source, and different
-solutions will be better for different programs; see section 13 for the
-specific requirements.
-
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU AGPL, see
-<https://www.gnu.org/licenses/>.

README.md

@@ -1,443 +0,0 @@
-[![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/)
-[![Tests](https://github.com/basicmachines-co/basic-memory/workflows/Tests/badge.svg)](https://github.com/basicmachines-co/basic-memory/actions)
-[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-![](https://badge.mcpx.dev?type=server 'MCP Server')
-![](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
-
-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://basicmachines.co
-- Documentation: https://memory.basicmachines.co
-
-## Pick up your conversation right where you left off
-
-- AI assistants can load context from local files in a new conversation
-- Notes are saved locally as Markdown files in real time
-- No project knowledge or special prompting required
-
-https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc
-
-## Quick Start
-
-```bash
-# Install with uv (recommended)
-uv tool install basic-memory
-
-# Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)
-# Add this to your config:
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uvx",
-      "args": [
-        "basic-memory",
-        "mcp"
-      ]
-    }
-  }
-}
-# Now in Claude Desktop, you can:
-# - Write notes with "Create a note about coffee brewing methods"
-# - Read notes with "What do I know about pour over coffee?"
-# - Search with "Find information about Ethiopian beans"
-
-```
-
-You can view shared context via files in `~/basic-memory` (default directory location).
-
-### Alternative Installation via Smithery
-
-You can use [Smithery](https://smithery.ai/server/@basicmachines-co/basic-memory) to automatically configure Basic
-Memory for Claude Desktop:
-
-```bash
-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. The
-Smithery server hosts the MCP server component, while your data remains stored locally as Markdown files.
-
-### Glama.ai
-
-<a href="https://glama.ai/mcp/servers/o90kttu9ym">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/o90kttu9ym/badge" alt="basic-memory MCP server" />
-</a>
-
-## Why Basic Memory?
-
-Most LLM interactions are ephemeral - you ask a question, get an answer, and everything is forgotten. Each conversation
-starts fresh, without the context or knowledge from previous ones. Current workarounds have limitations:
-
-- Chat histories capture conversations but aren't structured knowledge
-- RAG systems can query documents but don't let LLMs write back
-- Vector databases require complex setups and often live in the cloud
-- Knowledge graphs typically need specialized tools to maintain
-
-Basic Memory addresses these problems with a simple approach: structured Markdown files that both humans and LLMs can
-read
-and write to. The key advantages:
-
-- **Local-first:** All knowledge stays in files you control
-- **Bi-directional:** Both you and the LLM read and write to the same files
-- **Structured yet simple:** Uses familiar Markdown with semantic patterns
-- **Traversable knowledge graph:** LLMs can follow links between topics
-- **Standard formats:** Works with existing editors like Obsidian
-- **Lightweight infrastructure:** Just local files indexed in a local SQLite database
-
-With Basic Memory, you can:
-
-- Have conversations that build on previous knowledge
-- Create structured notes during natural conversations
-- Have conversations with LLMs that remember what you've discussed before
-- Navigate your knowledge graph semantically
-- 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
-
-Let's say you're exploring coffee brewing methods and want to capture your knowledge. Here's how it works:
-
-1. Start by chatting normally:
-
-```
-I've been experimenting with different coffee brewing methods. Key things I've learned:
-
-- Pour over gives more clarity in flavor than French press
-- Water temperature is critical - around 205°F seems best
-- Freshly ground beans make a huge difference
-```
-
-... continue conversation.
-
-2. Ask the LLM to help structure this knowledge:
-
-```
-"Let's write a note about coffee brewing methods."
-```
-
-LLM creates a new Markdown file on your system (which you can see instantly in Obsidian or your editor):
-
-```markdown
----
-title: Coffee Brewing Methods
-permalink: coffee-brewing-methods
-tags:
-- coffee
-- brewing
----
-
-# Coffee Brewing Methods
-
-## Observations
-
-- [method] Pour over provides more clarity and highlights subtle flavors
-- [technique] Water temperature at 205°F (96°C) extracts optimal compounds
-- [principle] Freshly ground beans preserve aromatics and flavor
-
-## Relations
-
-- relates_to [[Coffee Bean Origins]]
-- requires [[Proper Grinding Technique]]
-- affects [[Flavor Extraction]]
-```
-
-The note embeds semantic content and links to other topics via simple Markdown formatting.
-
-3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
-
-- Realtime sync can be enabled via running `basic-memory sync --watch`
-
-4. In a chat with the LLM, you can reference a topic:
-
-```
-Look at `coffee-brewing-methods` for context about pour over coffee
-```
-
-The LLM can now build rich context from the knowledge graph. For example:
-
-```
-Following relation 'relates_to [[Coffee Bean Origins]]':
-- Found information about Ethiopian Yirgacheffe
-- Notes on Colombian beans' nutty profile
-- Altitude effects on bean characteristics
-
-Following relation 'requires [[Proper Grinding Technique]]':
-- Burr vs. blade grinder comparisons
-- Grind size recommendations for different methods
-- Impact of consistent particle size on extraction
-```
-
-Each related document can lead to more context, building a rich semantic understanding of your knowledge base.
-
-This creates a two-way flow where:
-
-- Humans write and edit Markdown files
-- LLMs read and write through the MCP protocol
-- Sync keeps everything consistent
-- All knowledge stays in local files.
-
-## Technical Implementation
-
-Under the hood, Basic Memory:
-
-1. Stores everything in Markdown files
-2. Uses a SQLite database for searching and indexing
-3. Extracts semantic meaning from simple Markdown patterns
-    - Files become `Entity` objects
-    - Each `Entity` can have `Observations`, or facts associated with it
-    - `Relations` connect entities together to form the knowledge graph
-4. Maintains the local knowledge graph derived from the files
-5. Provides bidirectional synchronization between files and the knowledge graph
-6. Implements the Model Context Protocol (MCP) for AI integration
-7. Exposes tools that let AI assistants traverse and manipulate the knowledge graph
-8. Uses memory:// URLs to reference entities across tools and conversations
-
-The file format is just Markdown with some simple markup:
-
-Each Markdown file has:
-
-### Frontmatter
-
-```markdown
-title: <Entity title>
-type: <The type of Entity> (e.g. note)
-permalink: <a uri slug>
-
-- <optional metadata> (such as tags) 
-```
-
-### Observations
-
-Observations are facts about a topic.
-They can be added by creating a Markdown list with a special format that can reference a `category`, `tags` using a
-"#" character, and an optional `context`.
-
-Observation Markdown format:
-
-```markdown
-- [category] content #tag (optional context)
-```
-
-Examples of observations:
-
-```markdown
-- [method] Pour over extracts more floral notes than French press
-- [tip] Grind size should be medium-fine for pour over #brewing
-- [preference] Ethiopian beans have bright, fruity flavors (especially from Yirgacheffe)
-- [fact] Lighter roasts generally contain more caffeine than dark roasts
-- [experiment] Tried 1:15 coffee-to-water ratio with good results
-- [resource] James Hoffman's V60 technique on YouTube is excellent
-- [question] Does water temperature affect extraction of different compounds differently?
-- [note] My favorite local shop uses a 30-second bloom time
-```
-
-### Relations
-
-Relations are links to other topics. They define how entities connect in the knowledge graph.
-
-Markdown format:
-
-```markdown
-- relation_type [[WikiLink]] (optional context)
-```
-
-Examples of relations:
-
-```markdown
-- pairs_well_with [[Chocolate Desserts]]
-- grown_in [[Ethiopia]]
-- contrasts_with [[Tea Brewing Methods]]
-- requires [[Burr Grinder]]
-- improves_with [[Fresh Beans]]
-- relates_to [[Morning Routine]]
-- inspired_by [[Japanese Coffee Culture]]
-- documented_in [[Coffee Journal]]
-```
-
-## Using with VS Code
-
-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)`.
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "basic-memory": {
-        "command": "uvx",
-        "args": ["basic-memory", "mcp"]
-      }
-    }
-  }
-}
-```
-
-Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
-
-```json
-{
-  "servers": {
-    "basic-memory": {
-      "command": "uvx",
-      "args": ["basic-memory", "mcp"]
-    }
-  }
-}
-```
-
-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/):
-
-1. Configure Claude Desktop to use Basic Memory:
-
-Edit your MCP configuration file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json`
-for OS X):
-
-```json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uvx",
-      "args": [
-        "basic-memory",
-        "mcp"
-      ]
-    }
-  }
-}
-```
-
-If you want to use a specific project (see [Multiple Projects](#multiple-projects) below), update your Claude Desktop
-config:
-
-```json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uvx",
-      "args": [
-        "basic-memory",
-        "mcp",
-        "--project",
-        "your-project-name"
-      ]
-    }
-  }
-}
-```
-
-2. Sync your knowledge:
-
-```bash
-# One-time sync of local knowledge updates
-basic-memory sync
-
-# 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
-read_content(path) - Read raw file content (text, images, binaries)
-view_note(identifier) - View notes as formatted artifacts
-edit_note(identifier, operation, content) - Edit notes incrementally
-move_note(identifier, destination_path) - Move notes with database consistency
-delete_note(identifier) - Delete notes from knowledge base
-```
-
-**Knowledge Graph Navigation:**
-```
-build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
-recent_activity(type, depth, timeframe) - Find recently updated information
-list_directory(dir_name, depth) - Browse directory contents with filtering
-```
-
-**Search & Discovery:**
-```
-search(query, page, page_size) - Search across your knowledge base
-```
-
-**Project Management:**
-```
-list_memory_projects() - List all available projects
-create_memory_project(project_name, project_path) - Create new projects
-get_current_project() - Show current project stats
-sync_status() - Check synchronization status
-```
-
-**Visualization:**
-```
-canvas(nodes, edges, title, folder) - Generate knowledge visualizations
-```
-
-5. Example prompts to try:
-
-```
-"Create a note about our project architecture decisions"
-"Find information about JWT authentication in my notes"
-"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?"
-```
-
-## Futher info
-
-See the [Documentation](https://memory.basicmachines.co/) for more info, including:
-
-- [Complete User Guide](https://docs.basicmemory.com/user-guide/)
-- [CLI tools](https://docs.basicmemory.com/guides/cli-reference/)
-- [Cloud CLI and Sync](https://docs.basicmemory.com/guides/cloud-cli/)
-- [Managing multiple Projects](https://docs.basicmemory.com/guides/cli-reference/#project)
-- [Importing data from OpenAI/Claude Projects](https://docs.basicmemory.com/guides/cli-reference/#import)
-
-## License
-
-AGPL-3.0
-
-Contributions are welcome. See the [Contributing](CONTRIBUTING.md) guide for info about setting up the project locally
-and submitting PRs.
-
-## Star History
-
-<a href="https://www.star-history.com/#basicmachines-co/basic-memory&Date">
- <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" />
- </picture>
-</a>
-
-Built with ♥️ by Basic Machines

SECURITY.md

@@ -1,13 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.x.x   | :white_check_mark: |
-
-## Reporting a Vulnerability
-
-Use this section to tell people how to report a vulnerability.
-
-If you find a vulnerability, please contact hello@basicmachines.co

docker-compose.yml

@@ -1,83 +0,0 @@
-# Docker Compose configuration for Basic Memory
-# See docs/Docker.md for detailed setup instructions
-
-version: '3.8'
-
-services:
-  basic-memory:
-    # Use pre-built image (recommended for most users)
-    image: ghcr.io/basicmachines-co/basic-memory:latest
-    
-    # Uncomment to build locally instead:
-    # build: .
-    
-    container_name: basic-memory-server
-    
-    # Volume mounts for knowledge directories and persistent data
-    volumes:
-
-      # Persistent storage for configuration and database
-      - basic-memory-config:/root/.basic-memory:rw
-
-      # Mount your knowledge directory (required)
-      # Change './knowledge' to your actual Obsidian vault or knowledge directory
-      - ./knowledge:/app/data:rw
-
-      # OPTIONAL: Mount additional knowledge directories for multiple projects
-      # - ./work-notes:/app/data/work:rw
-      # - ./personal-notes:/app/data/personal:rw
-
-      # You can edit the project config manually in the mounted config volume
-      # The default project will be configured to use /app/data
-    environment:
-      # Project configuration
-      - BASIC_MEMORY_DEFAULT_PROJECT=main
-      
-      # Enable real-time file synchronization (recommended for Docker)
-      - BASIC_MEMORY_SYNC_CHANGES=true
-      
-      # Logging configuration
-      - BASIC_MEMORY_LOG_LEVEL=INFO
-      
-      # Sync delay in milliseconds (adjust for performance vs responsiveness)
-      - BASIC_MEMORY_SYNC_DELAY=1000
-    
-    # Port exposure for HTTP transport (only needed if not using STDIO)
-    ports:
-      - "8000:8000"
-    
-    # Command with SSE transport (configurable via environment variables above)
-    # IMPORTANT: The SSE and streamable-http endpoints are not secured
-    command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
-    
-    # Container management
-    restart: unless-stopped
-    
-    # Health monitoring
-    healthcheck:
-      test: ["CMD", "basic-memory", "--version"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 30s
-    
-    # Optional: Resource limits
-    # deploy:
-    #   resources:
-    #     limits:
-    #       memory: 512M
-    #       cpus: '0.5'
-    #     reservations:
-    #       memory: 256M
-    #       cpus: '0.25'
-
-volumes:
-  # Named volume for persistent configuration and database
-  # This ensures your configuration and knowledge graph persist across container restarts
-  basic-memory-config:
-    driver: local
-
-# Network configuration (optional)
-# networks:
-#   basic-memory-net:
-#     driver: bridge

docs/Docker.md

@@ -1,365 +0,0 @@
-# Docker Setup Guide
-
-Basic Memory can be run in Docker containers to provide a consistent, isolated environment for your knowledge management
-system. This is particularly useful for integrating with existing Dockerized MCP servers or for deployment scenarios.
-
-## Quick Start
-
-### Option 1: Using Pre-built Images (Recommended)
-
-Basic Memory provides pre-built Docker images on GitHub Container Registry that are automatically updated with each release.
-
-1. **Use the official image directly:**
-   ```bash
-   docker run -d \
-     --name basic-memory-server \
-     -p 8000:8000 \
-     -v /path/to/your/obsidian-vault:/app/data:rw \
-     -v basic-memory-config:/app/.basic-memory:rw \
-     ghcr.io/basicmachines-co/basic-memory:latest
-   ```
-
-2. **Or use Docker Compose with the pre-built image:**
-   ```yaml
-   version: '3.8'
-   services:
-     basic-memory:
-       image: ghcr.io/basicmachines-co/basic-memory:latest
-       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
-   ```
-
-### Option 2: Using Docker Compose (Building Locally)
-
-1. **Clone the repository:**
-   ```bash
-   git clone https://github.com/basicmachines-co/basic-memory.git
-   cd basic-memory
-   ```
-
-2. **Update the docker-compose.yml:**
-   Edit the volume mount to point to your Obsidian vault:
-   ```yaml
-   volumes:
-     # Change './obsidian-vault' to your actual directory path
-     - /path/to/your/obsidian-vault:/app/data:rw
-   ```
-
-3. **Start the container:**
-   ```bash
-   docker-compose up -d
-   ```
-
-### Option 3: Using Docker CLI
-
-```bash
-# Build the image
-docker build -t basic-memory .
-
-# Run with volume mounting
-docker run -d \
-  --name basic-memory-server \
-  -v /path/to/your/obsidian-vault:/app/data:rw \
-  -v basic-memory-config:/app/.basic-memory:rw \
-  -e BASIC_MEMORY_DEFAULT_PROJECT=main \
-  basic-memory
-```
-
-## Configuration
-
-### Volume Mounts
-
-Basic Memory requires several volume mounts for proper operation:
-
-1. **Knowledge Directory** (Required):
-   ```yaml
-   - /path/to/your/obsidian-vault:/app/data:rw
-   ```
-   Mount your Obsidian vault or knowledge base directory.
-
-2. **Configuration and Database** (Recommended):
-   ```yaml
-   - 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 /app/.basic-memory/config.json after Basic Memory starts.
-
-3. **Multiple Projects** (Optional):
-   ```yaml
-   - /path/to/project1:/app/data/project1:rw
-   - /path/to/project2:/app/data/project2:rw
-   ```
-
-You can edit the basic-memory config.json file located in the /app/.basic-memory/config.json
-
-## CLI Commands via Docker
-
-You can run Basic Memory CLI commands inside the container using `docker exec`:
-
-### Basic Commands
-
-```bash
-# Check status
-docker exec basic-memory-server basic-memory status
-
-# Sync files
-docker exec basic-memory-server basic-memory sync
-
-# Show help
-docker exec basic-memory-server basic-memory --help
-```
-
-### Managing Projects with Volume Mounts
-
-When using Docker volumes, you'll need to configure projects to point to your mounted directories:
-
-1. **Check current configuration:**
-   ```bash
-   docker exec basic-memory-server cat /app/.basic-memory/config.json
-   ```
-
-2. **Add a project for your mounted volume:**
-   ```bash
-   # If you mounted /path/to/your/vault to /app/data
-   docker exec basic-memory-server basic-memory project create my-vault /app/data
-   
-   # Set it as default
-   docker exec basic-memory-server basic-memory project set-default my-vault
-   ```
-
-3. **Sync the new project:**
-   ```bash
-   docker exec basic-memory-server basic-memory sync
-   ```
-
-### Example: Setting up an Obsidian Vault
-
-If you mounted your Obsidian vault like this in docker-compose.yml:
-```yaml
-volumes:
-  - /Users/yourname/Documents/ObsidianVault:/app/data:rw
-```
-
-Then configure it:
-```bash
-# Create project pointing to mounted vault
-docker exec basic-memory-server basic-memory project create obsidian /app/data
-
-# Set as default
-docker exec basic-memory-server basic-memory project set-default obsidian
-
-# Sync to index all files
-docker exec basic-memory-server basic-memory sync
-```
-
-### Environment Variables
-
-Configure Basic Memory using environment variables:
-
-```yaml
-environment:
-
-  # Default project
-  - BASIC_MEMORY_DEFAULT_PROJECT=main
-
-  # Enable real-time sync
-  - BASIC_MEMORY_SYNC_CHANGES=true
-
-  # Logging level
-  - BASIC_MEMORY_LOG_LEVEL=INFO
-
-  # Sync delay in milliseconds
-  - BASIC_MEMORY_SYNC_DELAY=1000
-```
-
-## File Permissions
-
-### Linux/macOS
-
-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
-# Build with custom UID/GID to match your user
-docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t basic-memory .
-
-# 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:
-
-1. Open Docker Desktop
-2. Go to Settings → Resources → File Sharing
-3. Add your knowledge directory path
-4. Apply & Restart
-
-## Troubleshooting
-
-### Common Issues
-
-1. **File Watching Not Working:**
-    - Ensure volume mounts are read-write (`:rw`)
-    - Check directory permissions
-    - On Linux, may need to increase inotify limits:
-      ```bash
-      echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
-      sudo sysctl -p
-      ```
-
-2. **Configuration Not Persisting:**
-    - Use named volumes for `/app/.basic-memory`
-    - Check volume mount permissions
-
-3. **Network Connectivity:**
-    - For HTTP transport, ensure port 8000 is exposed
-    - Check firewall settings
-
-### Debug Mode
-
-Run with debug logging:
-
-```yaml
-environment:
-  - BASIC_MEMORY_LOG_LEVEL=DEBUG
-```
-
-View logs:
-
-```bash
-docker-compose logs -f basic-memory
-```
-
-
-## Security Considerations
-
-1. **Docker Security:**
-   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. 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
-   a network.
-
-4. **IMPORTANT:** The HTTP endpoints have no authorization. They should not be exposed on a public network.  
-
-## Integration Examples
-
-### Claude Desktop with Docker
-
-The recommended way to connect Claude Desktop to the containerized Basic Memory is using `mcp-proxy`, which converts the HTTP transport to STDIO that Claude Desktop expects:
-
-1. **Start the Docker container:**
-   ```bash
-   docker-compose up -d
-   ```
-
-2. **Configure Claude Desktop** to use mcp-proxy:
-   ```json
-   {
-     "mcpServers": {
-       "basic-memory": {
-         "command": "uvx",
-         "args": [
-           "mcp-proxy",
-           "http://localhost:8000/mcp"
-         ]
-       }
-     }
-   }
-   ```
-
-
-## Support
-
-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 /app`
-
-For general Basic Memory support, see the main [README](../README.md)
-and [documentation](https://memory.basicmachines.co/).
-
-## GitHub Container Registry Images
-
-### Available Images
-
-Pre-built Docker images are available on GitHub Container Registry at [`ghcr.io/basicmachines-co/basic-memory`](https://github.com/basicmachines-co/basic-memory/pkgs/container/basic-memory).
-
-**Supported architectures:**
-- `linux/amd64` (Intel/AMD x64)
-- `linux/arm64` (ARM64, including Apple Silicon)
-
-**Available tags:**
-- `latest` - Latest stable release
-- `v0.13.8`, `v0.13.7`, etc. - Specific version tags
-- `v0.13`, `v0.12`, etc. - Major.minor tags
-
-### Automated Builds
-
-Docker images are automatically built and published when new releases are tagged:
-
-1. **Release Process:** When a git tag matching `v*` (e.g., `v0.13.8`) is pushed, the CI workflow automatically:
-   - Builds multi-platform Docker images
-   - Pushes to GitHub Container Registry with appropriate tags
-   - Uses native GitHub integration for seamless publishing
-
-2. **CI/CD Pipeline:** The Docker workflow includes:
-   - Multi-platform builds (AMD64 and ARM64)
-   - Layer caching for faster builds
-   - Automatic tagging with semantic versioning
-   - Security scanning and optimization
-
-### Setup Requirements (For Maintainers)
-
-GitHub Container Registry integration is automatic for this repository:
-
-1. **No external setup required** - GHCR is natively integrated with GitHub
-2. **Automatic permissions** - Uses `GITHUB_TOKEN` with `packages: write` permission
-3. **Public by default** - Images are automatically public for public repositories
-
-The Docker CI workflow (`.github/workflows/docker.yml`) handles everything automatically when version tags are pushed.

docs/character-handling.md

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

@@ -1,730 +0,0 @@
-# Basic Memory Cloud CLI Guide
-
-The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using a **cloud mode toggle**. When cloud mode is enabled, all your regular `bm` commands work transparently with the cloud instead of locally.
-
-## Overview
-
-The cloud CLI enables you to:
-- **Toggle cloud mode** with `bm cloud login` / `bm cloud logout`
-- **Use regular commands in cloud mode**: `bm project`, `bm sync`, `bm tool` all work with cloud
-- **Upload local files** directly to cloud projects via `bm cloud upload`
-- **Bidirectional sync** with rclone bisync (recommended for most users)
-- **Direct file access** via rclone mount (alternative workflow)
-- **Integrity verification** with `bm cloud check`
-- **Automatic project creation** from local directories
-
-## 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.
-
-## The Cloud Mode Paradigm
-
-Basic Memory Cloud follows the **Dropbox/iCloud model** - a single cloud space containing all your projects, not per-project connections.
-
-**How it works:**
-- One login per machine: `bm cloud login`
-- One sync directory: `~/basic-memory-cloud-sync/` (all projects)
-- Projects are folders within your cloud space
-- All regular commands work in cloud mode
-
-**Why this model:**
-- ✅ Single set of credentials (not N per project)
-- ✅ One rclone process (not N processes)
-- ✅ Familiar pattern (like Dropbox)
-- ✅ Simple operations (setup once, sync anytime)
-- ✅ Natural scaling (add projects = add folders)
-
-## Quick Start
-
-### 1. Enable Cloud Mode
-
-Authenticate and enable cloud mode for all commands:
-
-```bash
-bm cloud login
-```
-
-This command will:
-1. Open your browser to the Basic Memory Cloud authentication page
-2. Prompt you to authorize the CLI application
-3. Store your authentication token locally
-4. **Enable cloud mode** - all CLI commands now work against cloud
-
-### 2. Set Up Sync
-
-Set up bidirectional file synchronization:
-
-```bash
-bm cloud setup
-```
-
-This will:
-1. Install rclone automatically (if needed)
-2. Configure sync credentials
-3. Create `~/basic-memory-cloud-sync/` directory
-4. Establish initial sync baseline
-
-**Alternative:** Use `bm cloud setup --mount` to set up mount instead of sync.
-
-### 3. Verify Setup
-
-Check that everything is working:
-
-```bash
-bm cloud status
-```
-
-You should see:
-- `Mode: Cloud (enabled)`
-- `Cloud instance is healthy`
-- Bisync status showing `✓ Initialized`
-
-### 4. Start Using Cloud
-
-Now all your regular commands work with the cloud:
-
-```bash
-# List cloud projects
-bm project list
-
-# Create cloud project
-bm project add "my-research"
-
-# Use MCP tools on cloud
-bm tool write-note --title "Hello" --folder "my-research" --content "Test"
-
-# Sync with cloud
-bm sync
-
-# Watch mode for continuous sync
-bm sync --watch
-```
-
-### 5. Disable Cloud Mode
-
-Return to local mode:
-
-```bash
-bm cloud logout
-```
-
-All commands now work locally again.
-
-## Working with Cloud Projects
-
-**Important:** When cloud mode is enabled, use regular `bm project` commands (not `bm cloud project`).
-
-### Listing Projects
-
-View all projects (cloud projects when cloud mode is enabled):
-
-```bash
-# In cloud mode - lists cloud projects
-bm project list
-
-# In local mode - lists local projects
-bm project list
-```
-
-### Creating Projects
-
-Create a new project (creates on cloud when cloud mode is enabled):
-
-```bash
-# In cloud mode - creates cloud project
-bm project add my-new-project
-
-# Create and set as default
-bm project add my-new-project --default
-```
-
-### Automatic Project Creation
-
-**New in SPEC-9:** Projects are automatically created when you create local directories!
-
-```bash
-# Create a local directory in your sync folder
-mkdir ~/basic-memory-cloud-sync/new-project
-echo "# Notes" > ~/basic-memory-cloud-sync/new-project/readme.md
-
-# Sync - automatically creates cloud project
-bm sync
-
-# Verify - project now exists on cloud
-bm project list
-```
-
-This Dropbox-like workflow means you don't need to manually coordinate projects between local and cloud.
-
-### Uploading Local Files
-
-You can directly upload local files or directories to cloud projects using `bm cloud upload`. This is useful for:
-- Migrating existing local projects to the cloud
-- Quickly uploading specific files or directories
-- One-time bulk uploads without setting up sync
-
-**Basic Usage:**
-
-```bash
-# Upload a directory to existing project
-bm cloud upload ~/my-notes --project research
-
-# Upload a single file
-bm cloud upload important-doc.md --project research
-```
-
-**Create Project On-the-Fly:**
-
-If the target project doesn't exist yet, use `--create-project`:
-
-```bash
-# Upload and create project in one step
-bm cloud upload ~/local-project --project new-research --create-project
-```
-
-**Skip Automatic Sync:**
-
-By default, the command syncs the project after upload to index the files. To skip this:
-
-```bash
-# Upload without triggering sync
-bm cloud upload ~/bulk-data --project archives --no-sync
-```
-
-**File Filtering:**
-
-The upload command respects `.bmignore` and `.gitignore` patterns, automatically excluding:
-- Hidden files (`.git`, `.DS_Store`)
-- Build artifacts (`node_modules`, `__pycache__`)
-- Database files (`*.db`, `*.db-wal`)
-- Environment files (`.env`)
-
-To customize what gets uploaded, edit `~/.basic-memory/.bmignore`.
-
-**Complete Example:**
-
-```bash
-# 1. Login to cloud
-bm cloud login
-
-# 2. Upload local project (creates project if needed)
-bm cloud upload ~/Documents/research-notes --project research --create-project
-
-# 3. Verify upload
-bm project list
-```
-
-**Notes:**
-- Files are uploaded directly via WebDAV (no sync setup required)
-- Uploads are immediate and don't require bisync or mount
-- Use this for migration or one-time uploads; use `bm sync` for ongoing synchronization
-
-## File Synchronization
-
-### The `bm sync` Command (Cloud Mode Aware)
-
-The `bm sync` command automatically adapts based on cloud mode:
-
-**In local mode:**
-```bash
-bm sync              # Indexes local files into database
-```
-
-**In cloud mode:**
-```bash
-bm sync              # Runs bisync + indexes files
-bm sync --watch      # Continuous sync every 60 seconds
-bm sync --interval 30  # Custom interval
-```
-
-The same command works everywhere - no need to remember different commands for local vs cloud!
-
-## Bidirectional Sync (bisync) - Recommended
-
-Bidirectional sync is the **recommended approach** for most users. It provides:
-- ✅ Offline access to all files
-- ✅ Automatic bidirectional synchronization
-- ✅ Conflict detection and resolution
-- ✅ Works with any editor or tool
-- ✅ Background watch mode
-
-### Setup
-
-Set up bisync (runs automatically if you used `bm cloud setup`):
-
-```bash
-bm cloud setup
-```
-
-Or set up with custom directory:
-
-```bash
-bm cloud setup --dir ~/my-sync-folder
-```
-
-### Running Sync
-
-Use the cloud-aware `bm sync` command:
-
-```bash
-# Manual sync
-bm sync
-
-# Watch mode (continuous sync)
-bm sync --watch
-
-# Custom interval (30 seconds)
-bm sync --watch --interval 30
-```
-
-### Bisync Profiles
-
-Bisync supports three conflict resolution strategies with different safety levels:
-
-| Profile | Conflict Resolution | Max Deletes | Use Case |
-|---------|-------------------|-------------|----------|
-| **balanced** | newer | 25 | Default, recommended for most users |
-| **safe** | none | 10 | Keep both versions on conflict |
-| **fast** | newer | 50 | Rapid iteration, higher delete tolerance |
-
-**Profile Details:**
-
-- **safe**:
-  - Conflict resolution: `none` (creates `.conflict` files for both versions)
-  - Max delete: 10 files per sync
-  - Best for: Critical data where you want manual conflict resolution
-
-- **balanced** (default):
-  - Conflict resolution: `newer` (auto-resolve to most recent file)
-  - Max delete: 25 files per sync
-  - Best for: General use with automatic conflict handling
-
-- **fast**:
-  - Conflict resolution: `newer` (auto-resolve to most recent file)
-  - Max delete: 50 files per sync
-  - Best for: Rapid development iteration with less restrictive safety checks
-
-**How to Select a Profile:**
-
-The default profile (`balanced`) is used automatically with `bm sync`:
-
-```bash
-# Uses balanced profile (default)
-bm sync
-```
-
-For advanced control, use `bm cloud bisync` with the `--profile` flag:
-
-```bash
-# Use safe mode
-bm cloud bisync --profile safe
-
-# Use fast mode
-bm cloud bisync --profile fast
-
-# Preview changes with specific profile
-bm cloud bisync --profile safe --dry-run
-```
-
-**Check Available Profiles:**
-
-```bash
-bm cloud status
-```
-
-This shows all available profiles with their settings.
-
-**Current Limitations:**
-
-- Profiles are hardcoded and cannot be customized
-- No config file option to change default profile
-- Profile settings (max_delete, conflict_resolve) cannot be modified without code changes
-- Profile selection only available via `bm cloud bisync --profile` (advanced command)
-
-### Establishing New Baseline
-
-If you need to force a complete resync:
-
-```bash
-bm cloud bisync --resync
-```
-
-**Warning:** This overwrites the sync state. Use only when recovering from errors.
-
-### Checking Sync Status
-
-View current sync status:
-
-```bash
-bm cloud status
-```
-
-This shows:
-- Cloud mode status
-- Instance health
-- Sync directory location
-- Last sync time
-- Available bisync profiles
-
-### Verifying Sync Integrity
-
-Check that local and cloud files match:
-
-```bash
-# Full integrity check
-bm cloud check
-
-# Faster one-way check
-bm cloud check --one-way
-```
-
-This uses `rclone check` to verify files match without transferring data.
-
-### Working with Bisync
-
-Create and edit files in `~/basic-memory-cloud-sync/`:
-
-```bash
-# Create a new note
-echo "# My Research" > ~/basic-memory-cloud-sync/my-project/notes.md
-
-# Edit with your favorite editor
-code ~/basic-memory-cloud-sync/my-project/
-
-# Sync changes to cloud
-bm sync
-```
-
-In watch mode, changes sync automatically:
-
-```bash
-# Start watch mode
-bm sync --watch
-
-# Edit files - they sync automatically every 60 seconds
-code ~/basic-memory-cloud-sync/my-project/
-```
-
-### Filter Configuration
-
-Bisync uses `.bmignore` patterns from `~/.basic-memory/.bmignore`:
-
-```bash
-# View current ignore patterns
-cat ~/.basic-memory/.bmignore
-
-# Edit ignore patterns
-code ~/.basic-memory/.bmignore
-```
-
-Example `.bmignore`:
-
-```gitignore
-# This file is used by 'bm cloud bisync' and file sync
-# Patterns use standard gitignore-style syntax
-
-# Hidden files (files starting with dot)
-- .*
-
-# Basic Memory internal files
-- memory.db/**
-- memory.db-shm/**
-- memory.db-wal/**
-- config.json/**
-
-# Version control
-- .git/**
-
-# Python
-- __pycache__/**
-- *.pyc
-- .venv/**
-
-# Node.js
-- node_modules/**
-```
-
-**Key points:**
-- ✅ **Global configuration** - One ignore file for all projects
-- ✅ **rclone filter syntax** - Patterns with `- ` prefix
-- ✅ **Automatic creation** - Created with defaults on first use
-- ✅ **Shared patterns** - Same patterns used by sync service
-
-## NFS Mount (Direct Access) - Alternative
-
-NFS mount provides direct file system access as an alternative to bisync. Use this if you prefer mounting files like a network drive.
-
-### Setup
-
-Set up mount instead of bisync:
-
-```bash
-bm cloud setup --mount
-```
-
-### Mounting Files
-
-Mount your cloud files:
-
-```bash
-# Mount with default settings
-bm cloud mount
-
-# Mount with specific profile
-bm cloud mount --profile fast
-```
-
-#### Mount Profiles
-
-- **balanced** (default): Balanced caching for general use
-- **streaming**: Optimized for large files
-- **fast**: Minimal verification for rapid access
-
-### Checking Mount Status
-
-View current mount status:
-
-```bash
-bm cloud status --mount
-```
-
-### Unmounting Files
-
-Unmount when done:
-
-```bash
-bm cloud unmount
-```
-
-### Working with Mounted Files
-
-Once mounted, files appear at `~/basic-memory-cloud/`:
-
-```bash
-# List cloud files
-ls ~/basic-memory-cloud/
-
-# Edit with your favorite editor
-code ~/basic-memory-cloud/my-project/
-
-# Changes are immediately synced to cloud
-echo "# Notes" > ~/basic-memory-cloud/my-project/readme.md
-```
-
-**Note:** Changes are written through to cloud immediately. There's no "sync" step needed.
-
-## Instance Management
-
-### Health Check
-
-Check if your cloud instance is healthy:
-
-```bash
-bm cloud status
-```
-
-This shows:
-- Cloud mode enabled/disabled
-- Instance health status
-- Instance version
-- Sync or mount status
-
-## 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 when logging in
-
-**Solution**: You need an active Basic Memory Cloud subscription to use cloud features.
-
-1. Visit the subscribe URL shown in the error message
-2. Sign up for a subscription
-3. Once your subscription is active, run `bm cloud login` again
-
-**Problem**: "Subscription Required" error for existing user
-
-**Solution**: Your subscription may have expired or been cancelled.
-
-1. Check your subscription status at [https://basicmemory.com/account](https://basicmemory.com/account)
-2. Renew your subscription if needed
-3. Run `bm cloud login` again
-
-Note: Access is immediately restored when your subscription becomes active.
-
-### Sync Issues
-
-**Problem**: "Bisync not initialized"
-
-**Solution**: Run setup or initialize with resync:
-
-```bash
-bm cloud setup
-# or
-bm cloud bisync --resync
-```
-
-**Problem**: "Too many deletes" error
-
-**Solution**: Bisync detected many deletions (safety check). Review changes and use a higher delete limit profile or force resync:
-
-```bash
-bm cloud bisync --profile fast  # Higher delete limit
-# or
-bm cloud bisync --resync        # Force baseline
-```
-
-**Problem**: Conflicts detected
-
-**Solution**: Bisync found files changed in both locations. Check sync directory for `.conflict` files:
-
-```bash
-ls ~/basic-memory-cloud-sync/**/*.conflict
-```
-
-Resolve conflicts manually, then sync again.
-
-### Connection Issues
-
-**Problem**: "Cannot connect to cloud instance"
-
-**Solution**: Check cloud status:
-
-```bash
-bm cloud status
-```
-
-If instance is down, wait a few minutes and retry. If problem persists, contact support.
-
-### Mount Issues
-
-**Problem**: "Mount point is busy"
-
-**Solution**: Unmount and remount:
-
-```bash
-bm cloud unmount
-bm cloud mount
-```
-
-**Problem**: "Permission denied" when accessing mounted files
-
-**Solution**: Check mount status and remount:
-
-```bash
-bm cloud status --mount
-bm cloud unmount
-bm cloud mount
-```
-
-## Security
-
-- **Authentication**: OAuth 2.1 with PKCE flow
-- **Tokens**: Stored securely in `~/.basic-memory/auth/token`
-- **Transport**: All data encrypted in transit (HTTPS)
-- **Credentials**: Scoped S3 credentials for sync/mount (read-write access to your tenant only)
-- **Isolation**: Your data is isolated from other tenants
-- **Ignore patterns**: Sensitive files (`.env`, credentials) automatically excluded
-
-## 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 sync status
-bm cloud status --mount          # Check cloud mode and mount status
-```
-
-### Setup
-
-```bash
-bm cloud setup                   # Setup bisync (default, recommended)
-bm cloud setup --mount           # Setup mount (alternative)
-bm cloud setup --dir ~/sync      # Custom sync directory
-```
-
-### Project Management (Cloud Mode Aware)
-
-When cloud mode is enabled, these commands work with cloud:
-
-```bash
-bm project list                  # List projects
-bm project add <name>            # Create project
-bm project add <name> --default  # Create and set as default
-bm project rm <name>             # Delete project
-bm project set-default <name>    # Set default project
-```
-
-### File Synchronization
-
-```bash
-bm sync                          # Sync files (local or cloud depending on mode)
-bm sync --watch                  # Continuous sync (cloud mode only)
-bm sync --interval 30            # Custom interval for watch mode
-
-# Advanced bisync commands
-bm cloud bisync                  # Run bisync manually
-bm cloud bisync --profile safe   # Use specific profile
-bm cloud bisync --dry-run        # Preview changes
-bm cloud bisync --resync         # Force new baseline
-bm cloud bisync --watch          # Continuous sync
-bm cloud bisync --verbose        # Show detailed output
-
-# Integrity verification
-bm cloud check                   # Full integrity check
-bm cloud check --one-way         # Faster one-way check
-```
-
-### File Upload
-
-```bash
-# Upload files/directories to cloud projects
-bm cloud upload <path> --project <name>              # Upload to existing project
-bm cloud upload <path> -p <name> --create-project    # Upload and create project
-bm cloud upload <path> -p <name> --no-sync           # Upload without syncing
-```
-
-### Direct File Access (Mount)
-
-```bash
-bm cloud mount                   # Mount cloud files
-bm cloud mount --profile fast    # Use specific profile
-bm cloud unmount                 # Unmount files
-```
-
-## Summary
-
-Basic Memory Cloud provides two workflows:
-
-### Recommended: Bidirectional Sync (bisync)
-1. `bm cloud login` - Authenticate once
-2. `bm cloud setup` - Configure sync once
-3. `bm sync` - Sync anytime (or use `--watch`)
-4. Work in `~/basic-memory-cloud-sync/`
-5. Changes sync bidirectionally
-
-### Alternative: Direct Mount
-1. `bm cloud login` - Authenticate once
-2. `bm cloud setup --mount` - Configure mount once
-3. `bm cloud mount` - Mount when needed
-4. Work in `~/basic-memory-cloud/`
-5. Changes write through immediately
-
-Both approaches work seamlessly with cloud mode - all your regular `bm` commands work with either workflow!

justfile

@@ -1,193 +0,0 @@
-# Basic Memory - Modern Command Runner
-
-# Install dependencies
-install:
-    pip install -e ".[dev]"
-    uv sync
-    @echo ""
-    @echo "💡 Remember to activate the virtual environment by running: source .venv/bin/activate"
-
-# Run unit tests only (fast, no coverage)
-test-unit:
-    uv run pytest -p pytest_mock -v --no-cov -n auto tests
-
-# Run integration tests only (fast, no coverage)
-test-int:
-    uv run pytest -p pytest_mock -v --no-cov -n auto test-int
-
-# Run all tests with unified coverage report
-test: test-unit test-int
-
-# Generate HTML coverage report
-coverage:
-    uv run pytest -p pytest_mock -v -n auto tests test-int --cov-report=html
-    @echo "Coverage report generated in htmlcov/index.html"
-
-# Lint and fix code (calls fix)
-lint: fix
-
-# Lint and fix code
-fix:
-    uv run ruff check --fix --unsafe-fixes src tests test-int
-
-# Type check code
-typecheck:
-    uv run pyright
-
-# Clean build artifacts and cache files
-clean:
-    find . -type f -name '*.pyc' -delete
-    find . -type d -name '__pycache__' -exec rm -r {} +
-    rm -rf installer/build/ installer/dist/ dist/
-    rm -f rw.*.dmg .coverage.*
-
-# Format code with ruff
-format:
-    uv run ruff format .
-
-# Run MCP inspector tool
-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 typecheck test
-
-# Generate Alembic migration with descriptive message
-migration message:
-    cd src/basic_memory/alembic && alembic revision --autogenerate -m "{{message}}"
-
-# Create a stable release (e.g., just release v0.13.2)
-release version:
-    #!/usr/bin/env bash
-    set -euo pipefail
-    
-    # Validate version format
-    if [[ ! "{{version}}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-        echo "❌ Invalid version format. Use: v0.13.2"
-        exit 1
-    fi
-    
-    # Extract version number without 'v' prefix
-    VERSION_NUM=$(echo "{{version}}" | sed 's/^v//')
-    
-    echo "🚀 Creating stable release {{version}}"
-    
-    # Pre-flight checks
-    echo "📋 Running pre-flight checks..."
-    if [[ -n $(git status --porcelain) ]]; then
-        echo "❌ Uncommitted changes found. Please commit or stash them first."
-        exit 1
-    fi
-    
-    if [[ $(git branch --show-current) != "main" ]]; then
-        echo "❌ Not on main branch. Switch to main first."
-        exit 1
-    fi
-    
-    # Check if tag already exists
-    if git tag -l "{{version}}" | grep -q "{{version}}"; then
-        echo "❌ Tag {{version}} already exists"
-        exit 1
-    fi
-    
-    # Run quality checks
-    echo "🔍 Running quality checks..."
-    just check
-    
-    # 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
-    
-    # Commit version update
-    git add src/basic_memory/__init__.py
-    git commit -m "chore: update version to $VERSION_NUM for {{version}} release"
-    
-    # Create and push tag
-    echo "🏷️  Creating tag {{version}}..."
-    git tag "{{version}}"
-    
-    echo "📤 Pushing to GitHub..."
-    git push origin main
-    git push origin "{{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"
-
-# Create a beta release (e.g., just beta v0.13.2b1)
-beta version:
-    #!/usr/bin/env bash
-    set -euo pipefail
-    
-    # Validate version format (allow beta/rc suffixes)
-    if [[ ! "{{version}}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(b[0-9]+|rc[0-9]+)$ ]]; then
-        echo "❌ Invalid beta version format. Use: v0.13.2b1 or v0.13.2rc1"
-        exit 1
-    fi
-    
-    # Extract version number without 'v' prefix
-    VERSION_NUM=$(echo "{{version}}" | sed 's/^v//')
-    
-    echo "🧪 Creating beta release {{version}}"
-    
-    # Pre-flight checks
-    echo "📋 Running pre-flight checks..."
-    if [[ -n $(git status --porcelain) ]]; then
-        echo "❌ Uncommitted changes found. Please commit or stash them first."
-        exit 1
-    fi
-    
-    if [[ $(git branch --show-current) != "main" ]]; then
-        echo "❌ Not on main branch. Switch to main first."
-        exit 1
-    fi
-    
-    # Check if tag already exists
-    if git tag -l "{{version}}" | grep -q "{{version}}"; then
-        echo "❌ Tag {{version}} already exists"
-        exit 1
-    fi
-    
-    # Run quality checks
-    echo "🔍 Running quality checks..."
-    just check
-    
-    # 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
-    
-    # Commit version update
-    git add src/basic_memory/__init__.py
-    git commit -m "chore: update version to $VERSION_NUM for {{version}} beta release"
-    
-    # Create and push tag
-    echo "🏷️  Creating tag {{version}}..."
-    git tag "{{version}}"
-    
-    echo "📤 Pushing to GitHub..."
-    git push origin main
-    git push origin "{{version}}"
-    
-    echo "✅ Beta release {{version}} created successfully!"
-    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"
-
-# List all available recipes
-default:
-    @just --list

llms-install.md

@@ -1,128 +0,0 @@
-# Basic Memory Installation Guide for LLMs
-
-This guide is specifically designed to help AI assistants like Cline install and configure Basic Memory. Follow these
-steps in order.
-
-## Installation Steps
-
-### 1. Install Basic Memory Package
-
-Use one of the following package managers to install:
-
-```bash
-# Install with uv (recommended)
-uv tool install basic-memory
-
-# Or with pip
-pip install basic-memory
-```
-
-### 2. Configure MCP Server
-
-Add the following to your config:
-
-```json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uvx",
-      "args": [
-        "basic-memory",
-        "mcp"
-      ]
-    }
-  }
-}
-```
-
-For Claude Desktop, this file is located at:
-
-macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
-Windows: %APPDATA%\Claude\claude_desktop_config.json
-
-### 3. Start Synchronization (optional)
-
-To synchronize files in real-time, run:
-
-```bash
-basic-memory sync --watch
-```
-
-Or for a one-time sync:
-
-```bash
-basic-memory sync
-```
-
-## Configuration Options
-
-### Custom Directory
-
-To use a directory other than the default `~/basic-memory`:
-
-```bash
-basic-memory project add custom-project /path/to/your/directory
-basic-memory project default custom-project
-```
-
-### Multiple Projects
-
-To manage multiple knowledge bases:
-
-```bash
-# List all projects
-basic-memory project list
-
-# Add a new project
-basic-memory project add work ~/work-basic-memory
-
-# Set default project
-basic-memory project default work
-```
-
-## Importing Existing Data
-
-### From Claude.ai
-
-```bash
-basic-memory import claude conversations path/to/conversations.json
-basic-memory import claude projects path/to/projects.json
-```
-
-### From ChatGPT
-
-```bash
-basic-memory import chatgpt path/to/conversations.json
-```
-
-### From MCP Memory Server
-
-```bash
-basic-memory import memory-json path/to/memory.json
-```
-
-## Troubleshooting
-
-If you encounter issues:
-
-1. Check that Basic Memory is properly installed:
-   ```bash
-   basic-memory --version
-   ```
-
-2. Verify the sync process is running:
-   ```bash
-   ps aux | grep basic-memory
-   ```
-
-3. Check sync output for errors:
-   ```bash
-   basic-memory sync --verbose
-   ```
-
-4. Check log output:
-   ```bash
-   cat ~/.basic-memory/basic-memory.log
-   ```
-
-For more detailed information, refer to the [full documentation](https://memory.basicmachines.co/).

pyproject.toml

@@ -1,132 +0,0 @@
-[project]
-name = "basic-memory"
-dynamic = ["version"]
-description = "Local-first knowledge management combining Zettelkasten with knowledge graphs"
-readme = "README.md"
-requires-python = ">=3.12"
-license = { text = "AGPL-3.0-or-later" }
-authors = [
-    { name = "Basic Machines", email = "hello@basic-machines.co" }
-]
-dependencies = [
-    "sqlalchemy>=2.0.0",
-    "pyyaml>=6.0.1",
-    "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-settings>=2.6.1",
-    "loguru>=0.7.3",
-    "pyright>=1.1.390",
-    "markdown-it-py>=3.0.0",
-    "python-frontmatter>=1.1.0",
-    "rich>=13.9.4",
-    "unidecode>=1.3.8",
-    "dateparser>=1.2.0",
-    "watchfiles>=1.0.4",
-    "fastapi[standard]>=0.115.8",
-    "alembic>=1.14.1",
-    "pillow>=11.1.0",
-    "pybars3>=0.9.7",
-    "fastmcp>=2.10.2",
-    "pyjwt>=2.10.1",
-    "python-dotenv>=1.1.0",
-    "pytest-aio>=1.9.0",
-    "aiofiles>=24.1.0", # Async file I/O
-]
-
-
-[project.urls]
-Homepage = "https://github.com/basicmachines-co/basic-memory"
-Repository = "https://github.com/basicmachines-co/basic-memory"
-Documentation = "https://github.com/basicmachines-co/basic-memory#readme"
-
-[project.scripts]
-basic-memory = "basic_memory.cli.main:app"
-bm = "basic_memory.cli.main:app"
-
-[build-system]
-requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
-build-backend = "hatchling.build"
-
-[tool.pytest.ini_options]
-pythonpath = ["src", "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\"')",
-]
-
-[tool.ruff]
-line-length = 100
-target-version = "py312"
-
-[dependency-groups]
-dev = [
-    "gevent>=24.11.1",
-    "icecream>=2.1.3",
-    "pytest>=8.3.4",
-    "pytest-cov>=4.1.0",
-    "pytest-mock>=3.12.0",
-    "pytest-asyncio>=0.24.0",
-    "pytest-xdist>=3.0.0",
-    "ruff>=0.1.6",
-    "freezegun>=1.5.5",
-]
-
-[tool.hatch.version]
-source = "uv-dynamic-versioning"
-
-[tool.uv-dynamic-versioning]
-vcs = "git"
-style = "pep440"
-bump = true
-fallback-version = "0.0.0"
-
-[tool.pyright]
-include = ["src/"]
-exclude = ["**/__pycache__"]
-ignore = ["test/"]
-defineConstant = { DEBUG = true }
-reportMissingImports = "error"
-reportMissingTypeStubs = false
-pythonVersion = "3.12"
-
-
-
-[tool.coverage.run]
-concurrency = ["thread", "gevent"]
-
-[tool.coverage.report]
-exclude_lines = [
-    "pragma: no cover",
-    "def __repr__",
-    "if self.debug:",
-    "if settings.DEBUG",
-    "raise AssertionError",
-    "raise NotImplementedError",
-    "if 0:",
-    "if __name__ == .__main__.:",
-    "class .*\\bProtocol\\):",
-    "@(abc\\.)?abstractmethod",
-]
-
-# Exclude specific modules that are difficult to test comprehensively
-omit = [
-    "*/external_auth_provider.py",  # External HTTP calls to OAuth providers
-    "*/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
-    "*/services/migration_service.py", # Complex migration scenarios
-]
-
-[tool.logfire]
-ignore_no_config = true

smithery.yaml

@@ -1,15 +0,0 @@
-# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
-
-startCommand:
-  type: stdio
-  configSchema:
-    # JSON Schema defining the configuration options for the MCP.
-    type: object
-    properties: {}
-    description: No configuration required. This MCP server runs using the default command.
-  commandFunction: |-
-    (config) => ({
-      command: 'basic-memory',
-      args: ['mcp']
-    })
-  exampleConfig: {}

specs/SPEC-1 Specification-Driven Development Process.md

@@ -1,156 +0,0 @@
----
-title: 'SPEC-1: Specification-Driven Development Process'
-type: spec
-permalink: specs/spec-1-specification-driven-development-process
-tags:
-- process
-- specification
-- development
-- meta
----
-
-# SPEC-1: Specification-Driven Development Process
-
-## Why
-We're implementing specification-driven development to solve the complexity and circular refactoring issues in our web development process. 
-Instead of getting lost in framework details and type gymnastics, we start with clear specifications that drive implementation.
-
-The default approach of adhoc development with AI agents tends to result in:
-- Circular refactoring cycles
-- Fighting framework complexity
-- Lost context between sessions
-- Unclear requirements and scope
-
-## What
-This spec defines our process for using basic-memory as the specification engine to build basic-memory-cloud. 
-We're creating a recursive development pattern where basic-memory manages the specs that drive the development of basic-memory-cloud.
-
-**Affected Areas:**
-- All future component development
-- Architecture decisions
-- Agent collaboration workflows
-- Knowledge management and context preservation
-
-## How (High Level)
-
-### Specification Structure
-
-Name: Spec names should be numbered sequentially, followed by a description eg. `SPEC-X - Simple Description.md`.
-See: [[Spec-2: Slash Commands Reference]]
-
-Every spec is a complete thought containing:
-- **Why**: The reasoning and problem being solved
-- **What**: What is affected or changed
-- **How**: High-level approach to implementation
-- **How to Evaluate**: Testing/validation procedure
-- Additional context as needed
-
-### Living Specification Format
-
-Specifications are **living documents** that evolve throughout implementation:
-
-**Progress Tracking:**
-- **Completed items**: Use ✅ checkmark emoji for implemented features
-- **Pending items**: Use `- [ ]` GitHub-style checkboxes for remaining tasks
-- **In-progress items**: Use `- [x]` when work is actively underway
-
-**Status Philosophy:**
-- **Avoid static status headers** like "COMPLETE" or "IN PROGRESS" that become stale
-- **Use checklists within content** to show granular implementation progress
-- **Keep specs informative** while providing clear progress visibility
-- **Update continuously** as understanding and implementation evolve
-
-**Example Format:**
-```markdown
-### ComponentName
-- ✅ Basic functionality implemented
-- ✅ Props and events defined
-- - [ ] Add sorting controls
-- - [ ] Improve accessibility
-- - [x] Currently implementing responsive design
-```
-
-This creates **git-friendly progress tracking** where `[ ]` easily becomes `[x]` or ✅ when completed, and specs remain valuable throughout the development lifecycle.
-
-
-## Claude Code 
-
-We will leverage Claude Code capabilities to make the process semi-automated. 
-
-- Slash commands: define repeatable steps in the process (create spec, implement, review, etc)
-- Agents: define roles to carry out instructions  (front end developer, baskend developer, etc)
-- MCP tools: enable agents to implement specs via actions (write code, test, etc)
-
-### Workflow
-1. **Create**: Write spec as complete thought in `/specs` folder
-2. **Discuss**: Iterate and refine through agent collaboration
-3. **Implement**: Hand spec to appropriate specialist agent
-4. **Validate**: Review implementation against spec criteria
-5. **Document**: Update spec with learnings and decisions
-
-### Slash Commands
-
-Claude slash commands are used to manage the flow.
-These are simple instructions to help make the process uniform. 
-They can be updated and refined as needed. 
-
-- `/spec create [name]` - Create new specification
-- `/spec status` - Show current spec states
-- `/spec implement [name]` - Hand to appropriate agent
-- `/spec review [name]` - Validate implementation
-
-### Agent Orchestration
-
-Agents are defined with clear roles, for instance:
-
-- **system-architect**: Creates high-level specs, ADRs, architectural decisions
-- **vue-developer**: Component specs, UI patterns, frontend architecture
-- **python-developer**: Implementation specs, technical details, backend logic
-- 
-- Each agent reads/updates specs through basic-memory tools. 
-
-## How to Evaluate
-
-### Success Criteria
-- Specs provide clear, actionable guidance for implementation
-- Reduced circular refactoring and scope creep
-- Persistent context across development sessions
-- Clean separation between "what/why" and implementation details
-- Specs record a history of what happened and why for historical context
-
-### Testing Procedure
-1. Create a spec for an existing problematic component
-2. Have an agent implement following only the spec
-3. Compare result quality and development speed vs. ad-hoc approach
-4. Measure context preservation across sessions
-5. Evaluate spec clarity and completeness
-
-### Metrics
-- Time from spec to working implementation
-- Number of refactoring cycles required
-- Agent understanding of requirements
-- Spec reusability for similar components
-
-## Notes
-- Start simple: specs are just complete thoughts, not heavy processes
-- Use basic-memory's knowledge graph to link specs, decisions, components
-- Let the process evolve naturally based on what works
-- Focus on solving the actual problem: Manage complexity in development
-
-## Observations
-
-- [problem] Web development without clear goals and documentation circular refactoring cycles #complexity
-- [solution] Specification-driven development reduces scope creep and context loss #process-improvement  
-- [pattern] basic-memory as specification engine creates recursive development loop #meta-development
-- [workflow] Five-step process: Create → Discuss → Implement → Validate → Document #methodology
-- [tool] Slash commands provide uniform process automation #automation
-- [agent-pattern] Three specialized agents handle different implementation domains #specialization
-- [success-metric] Time from spec to working implementation measures process efficiency #measurement
-- [learning] Process should evolve naturally based on what works in practice #adaptation
-- [format] Living specifications use checklists for progress tracking instead of static status headers #documentation
-- [evolution] Specs evolve throughout implementation maintaining value as working documents #continuous-improvement
-
-## Relations
-
-- spec [[Spec-2: Slash Commands Reference]]
-- spec [[Spec-3: Agent Definitions]]

specs/SPEC-11 Basic Memory API Performance Optimization.md

@@ -1,245 +0,0 @@
----
-title: 'SPEC-11: Basic Memory API Performance Optimization'
-type: spec
-permalink: specs/spec-11-basic-memory-api-performance-optimization
-tags:
-- performance
-- api
-- mcp
-- database
-- cloud
----
-
-# SPEC-11: Basic Memory API Performance Optimization
-
-## Why
-
-The Basic Memory API experiences significant performance issues in cloud environments due to expensive per-request initialization. MCP tools making
-HTTP requests to the API suffer from 350ms-2.6s latency overhead **before** any actual operation occurs.
-
-**Root Cause Analysis:**
-- GitHub Issue #82 shows repeated initialization sequences in logs (16:29:35 and 16:49:58)
-- Each MCP tool call triggers full database initialization + project reconciliation
-- `get_engine_factory()` dependency calls `db.get_or_create_db()` on every request
-- `reconcile_projects_with_config()` runs expensive sync operations repeatedly
-
-**Performance Impact:**
-- Database connection setup: ~50-100ms per request
-- Migration checks: ~100-500ms per request
-- Project reconciliation: ~200ms-2s per request
-- **Total overhead**: ~350ms-2.6s per MCP tool call
-
-This creates compounding effects with tenant auto-start delays and increases timeout risk in cloud deployments.
-
-Github issue: https://github.com/basicmachines-co/basic-memory-cloud/issues/82
-
-## What
-
-This optimization affects the **core basic-memory repository** components:
-
-1. **API Lifespan Management** (`src/basic_memory/api/app.py`)
- - Cache database connections in app state during startup
- - Avoid repeated expensive initialization
-
-2. **Dependency Injection** (`src/basic_memory/deps.py`)
- - Modify `get_engine_factory()` to use cached connections
- - Eliminate per-request database setup
-
-3. **Initialization Service** (`src/basic_memory/services/initialization.py`)
- - Add caching/throttling to project reconciliation
- - Skip expensive operations when appropriate
-
-4. **Configuration** (`src/basic_memory/config.py`)
- - Add optional performance flags for cloud environments
-
-**Backwards Compatibility**: All changes must be backwards compatible with existing CLI and non-cloud usage.
-
-## How (High Level)
-
-### Phase 1: Cache Database Connections (Critical - 80% of gains)
-
-**Problem**: `get_engine_factory()` calls `db.get_or_create_db()` per request
-**Solution**: Cache database engine/session in app state during lifespan
-
-1. **Modify API Lifespan** (`api/app.py`):
- ```python
- @asynccontextmanager
- async def lifespan(app: FastAPI):
-     app_config = ConfigManager().config
-     await initialize_app(app_config)
-
-     # Cache database connection in app state
-     engine, session_maker = await db.get_or_create_db(app_config.database_path)
-     app.state.engine = engine
-     app.state.session_maker = session_maker
-
-     # ... rest of startup logic
-```
-
-2. Modify Dependency Injection (deps.py):
-```python
-async def get_engine_factory(
-  request: Request
-) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
-  """Get cached engine and session maker from app state."""
-  return request.app.state.engine, request.app.state.session_maker
-```
-Phase 2: Optimize Project Reconciliation (Secondary - 20% of gains)
-
-Problem: reconcile_projects_with_config() runs expensive sync repeatedly
-Solution: Add module-level caching with time-based throttling
-
-1. Add Reconciliation Cache (services/initialization.py):
-```ptyhon
-_project_reconciliation_completed = False
-_last_reconciliation_time = 0
-
-async def reconcile_projects_with_config(app_config, force=False):
-  # Skip if recently completed (within 60 seconds) unless forced
-  if recently_completed and not force:
-      return
-  # ... existing logic
-```
-Phase 3: Cloud Environment Flags (Optional)
-
-Problem: Force expensive initialization in production environments
-Solution: Add skip flags for cloud/stateless deployments
-
-1. Add Config Flag (config.py):
-skip_initialization_sync: bool = Field(default=False)
-2. Configure in Cloud (basic-memory-cloud integration):
-BASIC_MEMORY_SKIP_INITIALIZATION_SYNC=true
-
-How to Evaluate
-
-Success Criteria
-
-1. Performance Metrics (Primary):
-- MCP tool response time reduced by 50%+ (measure before/after)
-- Database connection overhead eliminated (0ms vs 50-100ms)
-- Migration check overhead eliminated (0ms vs 100-500ms)
-- Project reconciliation overhead reduced by 90%+
-2. Load Testing:
-- Concurrent MCP tool calls maintain performance
-- No memory leaks in cached connections
-- Database connection pool behaves correctly
-3. Functional Correctness:
-- All existing API endpoints work identically
-- MCP tools maintain full functionality
-- CLI operations unaffected
-- Database migrations still execute properly
-4. Backwards Compatibility:
-- No breaking changes to existing APIs
-- Config changes are optional with safe defaults
-- Non-cloud deployments work unchanged
-
-Testing Strategy
-
-Performance Testing:
-# Before optimization
-time basic-memory-mcp-tools write_note "test" "content" "folder"
-# Measure: ~1-3 seconds
-
-# After optimization  
-time basic-memory-mcp-tools write_note "test" "content" "folder"
-# Target: <500ms
-
-Load Testing:
-# Multiple concurrent MCP tool calls
-for i in {1..10}; do
-basic-memory-mcp-tools search "test" &
-done
-wait
-# Verify: No degradation, consistent response times
-
-Regression Testing:
-# Full basic-memory test suite
-just test
-# All tests must pass
-
-# Integration tests with cloud deployment
-# Verify MCP gateway → API → database flow works
-
-Validation Checklist
-
-- Phase 1 Complete: Database connections cached, dependency injection optimized
-- Performance Benchmark: 50%+ improvement in MCP tool response times
-- Memory Usage: No leaks in cached connections over 24h+ periods
-- Stress Testing: 100+ concurrent requests maintain performance
-- Backwards Compatibility: All existing functionality preserved
-- Documentation: Performance optimization documented in README
-- Cloud Integration: basic-memory-cloud sees performance benefits
-
-## Implementation Status ✅ COMPLETED
-
-**Implementation Date**: 2025-09-26
-**Branch**: `feature/spec-11-api-performance-optimization`
-**Commit**: `771f60b`
-
-### ✅ Phase 1: Database Connection Caching - IMPLEMENTED
-
-**Files Modified:**
-- `src/basic_memory/api/app.py` - Added database connection caching in app.state
-- `src/basic_memory/deps.py` - Updated get_engine_factory() to use cached connections
-- `src/basic_memory/config.py` - Added skip_initialization_sync configuration flag
-
-**Implementation Details:**
-1. **API Lifespan Caching**: Database engine and session_maker cached in app.state during startup
-2. **Dependency Injection Optimization**: get_engine_factory() now returns cached connections instead of calling get_or_create_db()
-3. **Project Reconciliation Removal**: Eliminated expensive reconcile_projects_with_config() from API startup
-4. **CLI Fallback Preserved**: Non-API contexts continue to work with fallback database initialization
-
-### ✅ Performance Validation - ACHIEVED
-
-**Live Testing Results** (2025-09-26 14:03-14:09):
-
-| Operation | Before | After | Improvement |
-|-----------|--------|-------|-------------|
-| `read_note` | 350ms-2.6s | **20ms** | **95-99% faster** |
-| `edit_note` | 350ms-2.6s | **218ms** | **75-92% faster** |
-| `search_notes` | 350ms-2.6s | **<500ms** | **Responsive** |
-| `list_memory_projects` | N/A | **<100ms** | **Fast** |
-
-**Key Achievements:**
-- ✅ **95-99% improvement** in read operations (primary workflow)
-- ✅ **75-92% improvement** in edit operations
-- ✅ **Zero overhead** for project switching
-- ✅ **Database connection overhead eliminated** (0ms vs 50-100ms)
-- ✅ **Project reconciliation delays removed** from API requests
-- ✅ **<500ms target achieved** for all operations except write (which includes file sync)
-
-### ✅ Backwards Compatibility - MAINTAINED
-
-- All existing functionality preserved
-- CLI operations unaffected
-- Fallback for non-API contexts maintained
-- No breaking changes to existing APIs
-- Optional configuration with safe defaults
-
-### ✅ Testing Validation - PASSED
-
-- Integration tests passing
-- Type checking clear
-- Linting checks passed
-- Live testing with real MCP tools successful
-- Multi-project workflows validated
-- Rapid project switching validated
-
-## Notes
-
-Implementation Priority:
-- ✅ Phase 1 COMPLETED: Database connection caching provides 95%+ performance gains
-- ⚪ Phase 2 NOT NEEDED: Project reconciliation removal achieved the goals
-- ⚪ Phase 3 INCLUDED: skip_initialization_sync flag added
-
-Risk Mitigation:
-- ✅ All changes backwards compatible implemented
-- ✅ Gradual implementation successful (Phase 1 → validation)
-- ✅ Easy rollback via configuration flags available
-
-Cloud Integration:
-- ✅ This optimization directly addresses basic-memory-cloud issue #82
-- ✅ Changes in core basic-memory will benefit all cloud tenants
-- ✅ No changes needed in basic-memory-cloud itself
-
-**Result**: SPEC-11 performance optimizations successfully implemented and validated. The 95-99% improvement in MCP tool response times exceeds the original 50-80% target, providing exceptional performance gains for cloud deployments and local usage.

specs/SPEC-14- Cloud Git Versioning & GitHub Backup.md

@@ -1,210 +0,0 @@
----
-title: 'SPEC-14: Cloud Git Versioning & GitHub Backup'
-type: spec
-permalink: specs/spec-14-cloud-git-versioning
-tags:
-- git
-- github
-- backup
-- versioning
-- cloud
-related:
-- specs/spec-9-multi-project-bisync
-- specs/spec-9-follow-ups-conflict-sync-and-observability
-status: deferred
----
-
-# SPEC-14: Cloud Git Versioning & GitHub Backup
-
-**Status: DEFERRED** - Postponed until multi-user/teams feature development. Using S3 versioning (SPEC-9.1) for v1 instead.
-
-## Why Deferred
-
-**Original goals can be met with simpler solutions:**
-- Version history → **S3 bucket versioning** (automatic, zero config)
-- Offsite backup → **Tigris global replication** (built-in)
-- Restore capability → **S3 version restore** (`bm cloud restore --version-id`)
-- Collaboration → **Deferred to teams/multi-user feature** (not v1 requirement)
-
-**Complexity vs value trade-off:**
-- Git integration adds: committer service, puller service, webhooks, LFS, merge conflicts
-- Risk: Loop detection between Git ↔ rclone bisync ↔ local edits
-- S3 versioning gives 80% of value with 5% of complexity
-
-**When to revisit:**
-- Teams/multi-user features (PR-based collaboration workflow)
-- User requests for commit messages and branch-based workflows
-- Need for fine-grained audit trail beyond S3 object metadata
-
----
-
-## Original Specification (for reference)
-
-## Why
-Early access users want **transparent version history**, easy **offsite backup**, and a familiar **restore/branching** workflow. Git/GitHub integration would provide:
-- Auditable history of every change (who/when/why)
-- Branches/PRs for review and collaboration
-- Offsite private backup under the user's control
-- Escape hatch: users can always `git clone` their knowledge base
-
-**Note:** These goals are now addressed via S3 versioning (SPEC-9.1) for single-user use case.
-
-## Goals
-- **Transparent**: Users keep using Basic Memory; Git runs behind the scenes.
-- **Private**: Push to a **private GitHub repo** that the user owns (or tenant org).
-- **Reliable**: No data loss, deterministic mapping of filesystem ↔ Git.
-- **Composable**: Plays nicely with SPEC‑9 bisync and upcoming conflict features (SPEC‑9 Follow‑Ups).
-
-**Non‑Goals (for v1):**
-- Fine‑grained per‑file encryption in Git history (can be layered later).
-- Large media optimization beyond Git LFS defaults.
-
-## User Stories
-1. *As a user*, I connect my GitHub and choose a private backup repo.
-2. *As a user*, every change I make in cloud (or via bisync) is **committed** and **pushed** automatically.
-3. *As a user*, I can **restore** a file/folder/project to a prior version.
-4. *As a power user*, I can **git pull/push** directly to collaborate outside the app.
-5. *As an admin*, I can enforce repo ownership (tenant org) and least‑privilege scopes.
-
-## Scope
-- **In scope:** Full repo backup of `/app/data/` (all projects) with optional selective subpaths.
-- **Out of scope (v1):** Partial shallow mirrors; encrypted Git; cross‑provider SCM (GitLab/Bitbucket).
-
-## Architecture
-### Topology
-- **Authoritative working tree**: `/app/data/` (bucket mount) remains the source of truth (SPEC‑9).
-- **Bare repo** lives alongside: `/app/git/${tenant}/knowledge.git` (server‑side).
-- **Mirror remote**: `github.com/<owner>/<repo>.git` (private).
-
-```mermaid
-flowchart LR
-  A[/Users & Agents/] -->|writes/edits| B[/app/data/]
-  B -->|file events| C[Committer Service]
-  C -->|git commit| D[(Bare Repo)]
-  D -->|push| E[(GitHub Private Repo)]
-  E -->|webhook (push)| F[Puller Service]
-  F -->|git pull/merge| D
-  D -->|checkout/merge| B
-```
-
-### Services
-- **Committer Service** (daemon):
-  - Watches `/app/data/` for changes (inotify/poll)
-  - Batches changes (debounce e.g. 2–5s)
-  - Writes `.bmmeta` (if present) into commit message trailer (see Follow‑Ups)
-  - `git add -A && git commit -m "chore(sync): <summary>
-
-BM-Meta: <json>"`
-  - Periodic `git push` to GitHub mirror (configurable interval)
-- **Puller Service** (webhook target):
-  - Receives GitHub webhook (push) → `git fetch`
-  - **Fast‑forward** merges to `main` only; reject non‑FF unless policy allows
-  - Applies changes back to `/app/data/` via clean checkout
-  - Emits sync events for Basic Memory indexers
-
-### Auth & Security
-- **GitHub App** (recommended): minimal scopes: `contents:read/write`, `metadata:read`, webhook.
-- Tenant‑scoped installation; repo created in user account or tenant org.
-- Tokens stored in KMS/secret manager; rotated automatically.
-- Optional policy: allow only **FF merges** on `main`; non‑FF requires PR.
-
-### Repo Layout
-- **Monorepo** (default): one repo per tenant mirrors `/app/data/` with subfolders per project.
-- Optional multi‑repo mode (later): one repo per project.
-
-### File Handling
-- Honor `.gitignore` generated from `.bmignore.rclone` + BM defaults (cache, temp, state).
-- **Git LFS** for large binaries (images, media) — auto track by extension/size threshold.
-- Normalize newline + Unicode (aligns with Follow‑Ups).
-
-### Conflict Model
-- **Primary concurrency**: SPEC‑9 Follow‑Ups (`.bmmeta`, conflict copies) stays the first line of defense.
-- **Git merges** are a **secondary** mechanism:
-  - Server only auto‑merges **text** conflicts when trivial (FF or clean 3‑way).
-  - Otherwise, create `name (conflict from <branch>, <ts>).md` and surface via events.
-
-### Data Flow vs Bisync
-- Bisync (rclone) continues between local sync dir ↔ bucket.
-- Git sits **cloud‑side** between bucket and GitHub.
-- On **pull** from GitHub → files written to `/app/data/` → picked up by indexers & eventually by bisync back to users.
-
-## CLI & UX
-New commands (cloud mode):
-- `bm cloud git connect` — Launch GitHub App installation; create private repo; store installation id.
-- `bm cloud git status` — Show connected repo, last push time, last webhook delivery, pending commits.
-- `bm cloud git push` — Manual push (rarely needed).
-- `bm cloud git pull` — Manual pull/FF (admin only by default).
-- `bm cloud snapshot -m "message"` — Create a tagged point‑in‑time snapshot (git tag).
-- `bm restore <path> --to <commit|tag>` — Restore file/folder/project to prior version.
-
-Settings:
-- `bm config set git.autoPushInterval=5s`
-- `bm config set git.lfs.sizeThreshold=10MB`
-- `bm config set git.allowNonFF=false`
-
-## Migration & Backfill
-- On connect, if repo empty: initial commit of entire `/app/data/`.
-- If repo has content: require **one‑time import** path (clone to staging, reconcile, choose direction).
-
-## Edge Cases
-- Massive deletes: gated by SPEC‑9 `max_delete` **and** Git pre‑push hook checks.
-- Case changes and rename detection: rely on git rename heuristics + Follow‑Ups move hints.
-- Secrets: default ignore common secret patterns; allow custom deny list.
-
-## Telemetry & Observability
-- Emit `git_commit`, `git_push`, `git_pull`, `git_conflict` events with correlation IDs.
-- `bm sync --report` extended with Git stats (commit count, delta bytes, push latency).
-
-## Phased Plan
-### Phase 0 — Prototype (1 sprint)
-- Server: bare repo init + simple committer (batch every 10s) + manual GitHub token.
-- CLI: `bm cloud git connect --token <PAT>` (dev‑only)
-- Success: edits in `/app/data/` appear in GitHub within 30s.
-
-### Phase 1 — GitHub App & Webhooks (1–2 sprints)
-- Switch to GitHub App installs; create private repo; store installation id.
-- Committer hardened (debounce 2–5s, backoff, retries).
-- Puller service with webhook → FF merge → checkout to `/app/data/`.
-- LFS auto‑track + `.gitignore` generation.
-- CLI surfaces status + logs.
-
-### Phase 2 — Restore & Snapshots (1 sprint)
-- `bm restore` for file/folder/project with dry‑run.
-- `bm cloud snapshot` tags + list/inspect.
-- Policy: PR‑only non‑FF, admin override.
-
-### Phase 3 — Selective & Multi‑Repo (nice‑to‑have)
-- Include/exclude projects; optional per‑project repos.
-- Advanced policies (branch protections, required reviews).
-
-## Acceptance Criteria
-- Changes to `/app/data/` are committed and pushed automatically within configurable interval (default ≤5s).
-- GitHub webhook pull results in updated files in `/app/data/` (FF‑only by default).
-- LFS configured and functioning; large files don't bloat history.
-- `bm cloud git status` shows connected repo and last push/pull times.
-- `bm restore` restores a file/folder to a prior commit with a clear audit trail.
-- End‑to‑end works alongside SPEC‑9 bisync without loops or data loss.
-
-## Risks & Mitigations
-- **Loop risk (Git ↔ Bisync)**: Writes to `/app/data/` → bisync → local → user edits → back again. *Mitigation*: Debounce, commit squashing, idempotent `.bmmeta` versioning, and watch exclusion windows during pull.
-- **Repo bloat**: Lots of binary churn. *Mitigation*: default LFS, size threshold, optional media‑only repo later.
-- **Security**: Token leakage. *Mitigation*: GitHub App with short‑lived tokens, KMS storage, scoped permissions.
-- **Merge complexity**: Non‑trivial conflicts. *Mitigation*: prefer FF; otherwise conflict copies + events; require PR for non‑FF.
-
-## Open Questions
-- Do we default to **monorepo** per tenant, or offer project‑per‑repo at connect time?
-- Should `restore` write to a branch and open a PR, or directly modify `main`?
-- How do we expose Git history in UI (timeline view) without users dropping to CLI?
-
-## Appendix: Sample Config
-```json
-{
-  "git": {
-    "enabled": true,
-    "repo": "https://github.com/<owner>/<repo>.git",
-    "autoPushInterval": "5s",
-    "allowNonFF": false,
-    "lfs": { "sizeThreshold": 10485760 }
-  }
-}
-```

specs/SPEC-15 Configuration Persistence via Tigris for Cloud Tenants.md

@@ -1,264 +0,0 @@
----
-title: 'SPEC-15: Configuration Persistence via Tigris for Cloud Tenants'
-type: spec
-permalink: specs/spec-14-config-persistence-tigris
-tags:
-- persistence
-- tigris
-- multi-tenant
-- infrastructure
-- configuration
-status: draft
----
-
-# SPEC-15: Configuration Persistence via Tigris for Cloud Tenants
-
-## Why
-
-We need to persist Basic Memory configuration across Fly.io deployments without using persistent volumes or external databases.
-
-**Current Problems:**
-- `~/.basic-memory/config.json` lost on every deployment (project configuration)
-- `~/.basic-memory/memory.db` lost on every deployment (search index)
-- Persistent volumes break clean deployment workflow
-- External databases (Turso) require per-tenant token management
-
-**The Insight:**
-The SQLite database is just an **index cache** of the markdown files. It can be rebuilt in seconds from the source markdown files in Tigris. Only the small `config.json` file needs true persistence.
-
-**Solution:**
-- Store `config.json` in Tigris bucket (persistent, small file)
-- Rebuild `memory.db` on startup from markdown files (fast, ephemeral)
-- No persistent volumes, no external databases, no token management
-
-## What
-
-Store Basic Memory configuration in the Tigris bucket and rebuild the database index on tenant machine startup.
-
-**Affected Components:**
-- `basic-memory/src/basic_memory/config.py` - Add configurable config directory
-
-**Architecture:**
-
-```bash
-# Tigris Bucket (persistent, mounted at /mnt/tigris)
-/mnt/tigris/
-  ├── .basic-memory/
-  │   └── config.json          # ← Project configuration (persistent, accessed via BASIC_MEMORY_CONFIG_DIR)
-  └── projects/                 # ← Markdown files (persistent)
-      ├── project1/
-      └── project2/
-
-# Fly Machine (ephemeral)
-~/.basic-memory/
-  └── memory.db                # ← Rebuilt on startup (fast local disk)
-```
-
-## How (High Level)
-
-### 1. Add Configurable Config Directory to Basic Memory
-
-Currently `ConfigManager` hardcodes `~/.basic-memory/config.json`. Add environment variable to override:
-
-```python
-# basic-memory/src/basic_memory/config.py
-
-class ConfigManager:
-    """Manages Basic Memory configuration."""
-
-    def __init__(self) -> None:
-        """Initialize the configuration manager."""
-        home = os.getenv("HOME", Path.home())
-        if isinstance(home, str):
-            home = Path(home)
-
-        # Allow override via environment variable
-        if config_dir := os.getenv("BASIC_MEMORY_CONFIG_DIR"):
-            self.config_dir = Path(config_dir)
-        else:
-            self.config_dir = home / DATA_DIR_NAME
-
-        self.config_file = self.config_dir / CONFIG_FILE_NAME
-
-        # Ensure config directory exists
-        self.config_dir.mkdir(parents=True, exist_ok=True)
-```
-
-### 2. Rebuild Database on Startup
-
-Basic Memory already has the sync functionality. Just ensure it runs on startup:
-
-```python
-# apps/api/src/basic_memory_cloud_api/main.py
-
-@app.on_event("startup")
-async def startup_sync():
-    """Rebuild database index from Tigris markdown files."""
-    logger.info("Starting database rebuild from Tigris")
-
-    # Initialize file sync (rebuilds index from markdown files)
-    app_config = ConfigManager().config
-    await initialize_file_sync(app_config)
-
-    logger.info("Database rebuild complete")
-```
-
-### 3. Environment Configuration
-
-```bash
-# Machine environment variables
-BASIC_MEMORY_CONFIG_DIR=/mnt/tigris/.basic-memory  # Config read/written directly to Tigris
-# memory.db stays in default location: ~/.basic-memory/memory.db (local ephemeral disk)
-```
-
-## Implementation Task List
-
-### Phase 1: Basic Memory Changes ✅
-- [x] Add `BASIC_MEMORY_CONFIG_DIR` environment variable support to `ConfigManager.__init__()`
-- [x] Test config loading from custom directory
-- [x] Update tests to verify custom config dir works
-
-### Phase 2: Tigris Bucket Structure
-- [ ] Ensure `.basic-memory/` directory exists in Tigris bucket on tenant creation
-- [ ] Initialize `config.json` in Tigris on first tenant deployment
-- [ ] Verify TigrisFS handles hidden directories correctly
-
-### Phase 3: Deployment Integration
-- [ ] Set `BASIC_MEMORY_CONFIG_DIR` environment variable in machine deployment
-- [ ] Ensure database rebuild runs on machine startup via initialization sync
-- [ ] Handle first-time tenant setup (no config exists yet)
-- [ ] Test deployment workflow with config persistence
-
-### Phase 4: Testing
-- [x] Unit tests for config directory override
-- [ ] Integration test: deploy → write config → redeploy → verify config persists
-- [ ] Integration test: deploy → add project → redeploy → verify project in config
-- [ ] Performance test: measure db rebuild time on startup
-
-### Phase 5: Documentation
-- [ ] Document config persistence architecture
-- [ ] Update deployment runbook
-- [ ] Document startup sequence and timing
-
-## How to Evaluate
-
-### Success Criteria
-
-1. **Config Persistence**
-   - [ ] config.json persists across deployments
-   - [ ] Projects list maintained across restarts
-   - [ ] No manual configuration needed after redeploy
-
-2. **Database Rebuild**
-   - [ ] memory.db rebuilt on startup in < 30 seconds
-   - [ ] All entities indexed correctly
-   - [ ] Search functionality works after rebuild
-
-3. **Performance**
-   - [ ] SQLite queries remain fast (local disk)
-   - [ ] Config reads acceptable (symlink to Tigris)
-   - [ ] No noticeable performance degradation
-
-4. **Deployment Workflow**
-   - [ ] Clean deployments without volumes
-   - [ ] No new external dependencies
-   - [ ] No secret management needed
-
-### Testing Procedure
-
-1. **Config Persistence Test**
-   ```bash
-   # Deploy tenant
-   POST /tenants → tenant_id
-
-   # Add a project
-   basic-memory project add "test-project" ~/test
-
-   # Verify config has project
-   cat /mnt/tigris/.basic-memory/config.json
-
-   # Redeploy machine
-   fly deploy --app basic-memory-{tenant_id}
-
-   # Verify project still exists
-   basic-memory project list
-   ```
-
-2. **Database Rebuild Test**
-   ```bash
-   # Create notes
-   basic-memory write "Test Note" --content "..."
-
-   # Redeploy (db lost)
-   fly deploy --app basic-memory-{tenant_id}
-
-   # Wait for startup sync
-   sleep 10
-
-   # Verify note is indexed
-   basic-memory search "Test Note"
-   ```
-
-3. **Performance Benchmark**
-   ```bash
-   # Time the startup sync
-   time basic-memory sync
-
-   # Should be < 30 seconds for typical tenant
-   ```
-
-## Benefits Over Alternatives
-
-**vs. Persistent Volumes:**
-- ✅ Clean deployment workflow
-- ✅ No volume migration needed
-- ✅ Simpler infrastructure
-
-**vs. Turso (External Database):**
-- ✅ No per-tenant token management
-- ✅ No external service dependencies
-- ✅ No additional costs
-- ✅ Simpler architecture
-
-**vs. SQLite on FUSE:**
-- ✅ Fast local SQLite performance
-- ✅ Only slow reads for small config file
-- ✅ Database queries remain fast
-
-## Implementation Assignment
-
-**Primary Agent:** `python-developer`
-- Add `BASIC_MEMORY_CONFIG_DIR` environment variable to ConfigManager
-- Update deployment workflow to set environment variable
-- Ensure startup sync runs correctly
-
-**Review Agent:** `system-architect`
-- Validate architecture simplicity
-- Review performance implications
-- Assess startup timing
-
-## Dependencies
-
-- **Internal:** TigrisFS must be working and stable
-- **Internal:** Basic Memory sync must be reliable
-- **Internal:** SPEC-8 (TigrisFS Integration) must be complete
-
-## Open Questions
-
-1. Should we add a health check that waits for db rebuild to complete?
-2. Do we need to handle very large knowledge bases (>10k entities) differently?
-3. Should we add metrics for startup sync duration?
-
-## References
-
-- Basic Memory sync: `basic-memory/src/basic_memory/services/initialization.py`
-- Config management: `basic-memory/src/basic_memory/config.py`
-- TigrisFS integration: SPEC-8
-
----
-
-**Status Updates:**
-
-- 2025-10-08: Pivoted from Turso to Tigris-based config persistence
-- 2025-10-08: Phase 1 complete - BASIC_MEMORY_CONFIG_DIR support added (PR #343)
-- Next: Implement Phases 2-3 in basic-memory-cloud repository

specs/SPEC-16 MCP Cloud Service Consolidation.md

@@ -1,719 +0,0 @@
----
-title: 'SPEC-16: MCP Cloud Service Consolidation'
-type: spec
-permalink: specs/spec-16-mcp-cloud-service-consolidation
-tags:
-- architecture
-- mcp
-- cloud
-- performance
-- deployment
-status: draft
----
-
-# SPEC-16: MCP Cloud Service Consolidation
-
-## Why
-
-### Original Architecture Constraints (Now Removed)
-
-The current architecture deploys MCP Gateway and Cloud Service as separate Fly.io apps:
-
-**Current Flow:**
-```
-LLM Client → MCP Gateway (OAuth) → Cloud Proxy (JWT + header signing) → Tenant API (JWT + header validation)
-            apps/mcp                apps/cloud /proxy                    apps/api
-```
-
-This separation was originally necessary because:
-1. **Stateful SSE requirement** - MCP needed server-sent events with session state for active project tracking
-2. **fastmcp.run limitation** - The FastMCP demo helper didn't support worker processes
-
-### Why These Constraints No Longer Apply
-
-1. **State externalized** - Project state moved from in-memory to LLM context (external state)
-2. **HTTP transport enabled** - Switched from SSE to stateless HTTP for MCP tools
-3. **Worker support added** - Converted from `fastmcp.run()` to `uvicorn.run()` with workers
-
-### Current Problems
-
-- **Unnecessary HTTP hop** - MCP tools call Cloud /proxy endpoint which calls tenant API
-- **Higher latency** - Extra network round trip for every MCP operation
-- **Increased costs** - Two separate Fly.io apps instead of one
-- **Complex deployment** - Two services to deploy, monitor, and maintain
-- **Resource waste** - Separate database connections, HTTP clients, telemetry overhead
-
-## What
-
-### Services Affected
-
-1. **apps/mcp** - MCP Gateway service (to be merged)
-2. **apps/cloud** - Cloud service (will receive MCP functionality)
-3. **basic-memory** - Update `async_client.py` to use direct calls
-4. **Deployment** - Consolidate Fly.io deployment to single app
-
-### Components Changed
-
-**Merged:**
-- MCP middleware and telemetry into Cloud app
-- MCP tools mounted on Cloud FastAPI instance
-- ProxyService used directly by MCP tools (not via HTTP)
-
-**Kept:**
-- `/proxy` endpoint (still needed by web UI)
-- All existing Cloud routes (provisioning, webhooks, etc.)
-- Dual validation in tenant API (JWT + signed headers)
-
-**Removed:**
-- apps/mcp directory
-- Separate MCP Fly.io deployment
-- HTTP calls from MCP tools to /proxy endpoint
-
-## How (High Level)
-
-### 1. Mount FastMCP on Cloud FastAPI App
-
-```python
-# apps/cloud/src/basic_memory_cloud/main.py
-
-from basic_memory.mcp.server import mcp
-from basic_memory_cloud_mcp.middleware import TelemetryMiddleware
-
-# Configure MCP OAuth
-auth_provider = AuthKitProvider(
-    authkit_domain=settings.authkit_domain,
-    base_url=settings.authkit_base_url,
-    required_scopes=[],
-)
-mcp.auth = auth_provider
-mcp.add_middleware(TelemetryMiddleware())
-
-# Mount MCP at /mcp endpoint
-mcp_app = mcp.http_app(path="/mcp", stateless_http=True)
-app.mount("/mcp", mcp_app)
-
-# Existing Cloud routes stay at root
-app.include_router(proxy_router)
-app.include_router(provisioning_router)
-# ... etc
-```
-
-### 2. Direct Tenant Transport (No HTTP Hop)
-
-Instead of calling `/proxy`, MCP tools call tenant APIs directly via custom httpx transport:
-
-```python
-# apps/cloud/src/basic_memory_cloud/transports/tenant_direct.py
-
-from httpx import AsyncBaseTransport, Request, Response
-from fastmcp.server.dependencies import get_http_headers
-import jwt
-
-class TenantDirectTransport(AsyncBaseTransport):
-    """Direct transport to tenant APIs, bypassing /proxy endpoint."""
-
-    async def handle_async_request(self, request: Request) -> Response:
-        # 1. Get JWT from current MCP request (via FastMCP DI)
-        http_headers = get_http_headers()
-        auth_header = http_headers.get("authorization") or http_headers.get("Authorization")
-        token = auth_header.replace("Bearer ", "")
-        claims = jwt.decode(token, options={"verify_signature": False})
-        workos_user_id = claims["sub"]
-
-        # 2. Look up tenant for user
-        tenant = await tenant_service.get_tenant_by_user_id(workos_user_id)
-
-        # 3. Build tenant app URL with signed headers
-        fly_app_name = f"{settings.tenant_prefix}-{tenant.id}"
-        target_url = f"https://{fly_app_name}.fly.dev{request.url.path}"
-
-        headers = dict(request.headers)
-        signer = create_signer(settings.bm_tenant_header_secret)
-        headers.update(signer.sign_tenant_headers(tenant.id))
-
-        # 4. Make direct call to tenant API
-        response = await self.client.request(
-            method=request.method, url=target_url,
-            headers=headers, content=request.content
-        )
-        return response
-```
-
-Then override basic-memory's client before mounting MCP:
-
-```python
-# apps/cloud/src/basic_memory_cloud/main.py
-
-from basic_memory.mcp import async_client
-from basic_memory_cloud.transports.tenant_direct import TenantDirectTransport
-
-# Override basic-memory's HTTP client with direct transport
-async_client.client = httpx.AsyncClient(
-    transport=TenantDirectTransport(),
-    base_url="http://direct"
-)
-
-# Now mount MCP - tools will use direct transport
-app.mount("/mcp", mcp_app)
-```
-
-**Key benefits:**
-- No changes to basic-memory code
-- Per-request tenant resolution via FastMCP DI
-- Eliminates HTTP hop entirely (~50 lines of code)
-- /proxy endpoint remains for web UI
-
-### 3. Keep /proxy Endpoint for Web UI
-
-The existing `/proxy` HTTP endpoint remains functional for:
-- Web UI requests
-- Future external API consumers
-- Backward compatibility
-
-### 4. Security: Maintain Dual Validation
-
-**Do NOT remove JWT validation from tenant API.** Keep defense in depth:
-
-```python
-# apps/api - Keep both validations
-1. JWT validation (from WorkOS token)
-2. Signed header validation (from Cloud/MCP)
-```
-
-This ensures if the Cloud service is compromised, attackers still cannot access tenant APIs without valid JWTs.
-
-### 5. Deployment Changes
-
-**Before:**
-- `apps/mcp/fly.template.toml` → MCP Gateway deployment
-- `apps/cloud/fly.template.toml` → Cloud Service deployment
-
-**After:**
-- Remove `apps/mcp/fly.template.toml`
-- Update `apps/cloud/fly.template.toml` to expose port 8000 for both /mcp and /proxy
-- Update deployment scripts to deploy single consolidated app
-
-
-## Basic Memory Dependency: Async Client Refactor
-
-### Problem
-The current `basic_memory.mcp.async_client` creates a module-level `client` at import time:
-```python
-client = create_client()  # Runs immediately when module is imported
-```
-
-This prevents dependency injection - by the time we can override it, tools have already imported it.
-
-### Solution: Context Manager Pattern with Auth at Client Creation
-
-Refactor basic-memory to use httpx's context manager pattern instead of module-level client.
-
-**Key principle:** Authentication happens at client creation time, not per-request.
-
-```python
-# basic_memory/src/basic_memory/mcp/async_client.py
-from contextlib import asynccontextmanager
-from httpx import AsyncClient, ASGITransport, Timeout
-
-# Optional factory override for dependency injection
-_client_factory = None
-
-def set_client_factory(factory):
-    """Override the default client factory (for cloud app, testing, etc)."""
-    global _client_factory
-    _client_factory = factory
-
-@asynccontextmanager
-async def get_client():
-    """Get an AsyncClient as a context manager.
-
-    Usage:
-        async with get_client() as client:
-            response = await client.get(...)
-    """
-    if _client_factory:
-        # Cloud app: custom transport handles everything
-        async with _client_factory() as client:
-            yield client
-    else:
-        # Default: create based on config
-        config = ConfigManager().config
-        timeout = Timeout(connect=10.0, read=30.0, write=30.0, pool=30.0)
-
-        if config.cloud_mode_enabled:
-            # CLI cloud mode: inject auth when creating client
-            from basic_memory.cli.auth import CLIAuth
-
-            auth = CLIAuth(
-                client_id=config.cloud_client_id,
-                authkit_domain=config.cloud_domain
-            )
-            token = await auth.get_valid_token()
-
-            if not token:
-                raise RuntimeError(
-                    "Cloud mode enabled but not authenticated. "
-                    "Run 'basic-memory cloud login' first."
-                )
-
-            # Auth header set ONCE at client creation
-            async with AsyncClient(
-                base_url=f"{config.cloud_host}/proxy",
-                headers={"Authorization": f"Bearer {token}"},
-                timeout=timeout
-            ) as client:
-                yield client
-        else:
-            # Local mode: ASGI transport
-            async with AsyncClient(
-                transport=ASGITransport(app=fastapi_app),
-                base_url="http://test",
-                timeout=timeout
-            ) as client:
-                yield client
-```
-
-**Tool Updates:**
-```python
-# Before: from basic_memory.mcp.async_client import client
-from basic_memory.mcp.async_client import get_client
-
-async def read_note(...):
-    # Before: response = await call_get(client, path, ...)
-    async with get_client() as client:
-        response = await call_get(client, path, ...)
-        # ... use response
-```
-
-**Cloud Usage:**
-```python
-from contextlib import asynccontextmanager
-from basic_memory.mcp import async_client
-
-@asynccontextmanager
-async def tenant_direct_client():
-    """Factory for creating clients with tenant direct transport."""
-    client = httpx.AsyncClient(
-        transport=TenantDirectTransport(),
-        base_url="http://direct",
-    )
-    try:
-        yield client
-    finally:
-        await client.aclose()
-
-# Before importing MCP tools:
-async_client.set_client_factory(tenant_direct_client)
-
-# Now import - tools will use our factory
-import basic_memory.mcp.tools
-```
-
-### Benefits
-- **No module-level state** - client created only when needed
-- **Proper cleanup** - context manager ensures `aclose()` is called
-- **Easy dependency injection** - factory pattern allows custom clients
-- **httpx best practices** - follows official recommendations
-- **Works for all modes** - stdio, cloud, testing
-
-### Architecture Simplification: Auth at Client Creation
-
-**Key design principle:** Authentication happens when creating the client, not on every request.
-
-**Three modes, three approaches:**
-
-1. **Local mode (ASGI)**
-   - No auth needed
-   - Direct in-process calls via ASGITransport
-
-2. **CLI cloud mode (HTTP)**
-   - Auth token from CLIAuth (stored in ~/.basic-memory/basic-memory-cloud.json)
-   - Injected as default header when creating AsyncClient
-   - Single auth check at client creation time
-
-3. **Cloud app mode (Custom Transport)**
-   - TenantDirectTransport handles everything
-   - Extracts JWT from FastMCP context per-request
-   - No interaction with inject_auth_header() logic
-
-**What this removes:**
-- `src/basic_memory/mcp/tools/headers.py` - entire file deleted
-- `inject_auth_header()` calls in all request helpers (call_get, call_post, etc.)
-- Per-request header manipulation complexity
-- Circular dependency concerns between async_client and auth logic
-
-**Benefits:**
-- Cleaner separation of concerns
-- Simpler request helper functions
-- Auth happens at the right layer (client creation)
-- Cloud app transport is completely independent
-
-### Refactor Summary
-
-This refactor achieves:
-
-**Simplification:**
-- Removes ~100 lines of per-request header injection logic
-- Deletes entire `headers.py` module
-- Auth happens once at client creation, not per-request
-
-**Decoupling:**
-- Cloud app's custom transport is completely independent
-- No interaction with basic-memory's auth logic
-- Each mode (local, CLI cloud, cloud app) has clean separation
-
-**Better Design:**
-- Follows httpx best practices (context managers)
-- Proper resource cleanup (client.aclose() guaranteed)
-- Easier testing via factory injection
-- No circular import risks
-
-**Three Distinct Modes:**
-1. Local: ASGI transport, no auth
-2. CLI cloud: HTTP transport with CLIAuth token injection
-3. Cloud app: Custom transport with per-request tenant routing
-
-### Implementation Plan Summary
-1. Create branch `async-client-context-manager` in basic-memory
-2. Update `async_client.py` with context manager pattern and CLIAuth integration
-3. Remove `inject_auth_header()` from all request helpers
-4. Delete `src/basic_memory/mcp/tools/headers.py`
-5. Update all MCP tools to use `async with get_client() as client:`
-6. Update CLI commands to use context manager and remove manual auth
-7. Remove `api_url` config field
-8. Update tests
-9. Update basic-memory-cloud to use branch: `basic-memory @ git+https://github.com/basicmachines-co/basic-memory.git@async-client-context-manager`
-
-Detailed breakdown in Phase 0 tasks below.
-
-### Implementation Notes
-
-**Potential Issues & Solutions:**
-
-1. **Circular Import** (async_client imports CLIAuth)
-   - **Risk:** CLIAuth might import something from async_client
-   - **Solution:** Use lazy import inside `get_client()` function
-   - **Already done:** Import is inside the function, not at module level
-
-2. **Test Fixtures**
-   - **Risk:** Tests using module-level client will break
-   - **Solution:** Update fixtures to use factory pattern
-   - **Example:**
-     ```python
-     @pytest.fixture
-     def mock_client_factory():
-         @asynccontextmanager
-         async def factory():
-             async with AsyncClient(...) as client:
-                 yield client
-         return factory
-     ```
-
-3. **Performance**
-   - **Risk:** Creating client per tool call might be expensive
-   - **Reality:** httpx is designed for this pattern, connection pooling at transport level
-   - **Mitigation:** Monitor performance, can optimize later if needed
-
-4. **CLI Cloud Commands Edge Cases**
-   - **Risk:** Token expires mid-operation
-   - **Solution:** CLIAuth.get_valid_token() already handles refresh
-   - **Validation:** Test cloud login → use tools → token refresh flow
-
-5. **Backward Compatibility**
-   - **Risk:** External code importing `client` directly
-   - **Solution:** Keep `create_client()` and `client` for one version, deprecate
-   - **Timeline:** Remove in next major version
-
-## Implementation Tasks
-
-### Phase 0: Basic Memory Refactor (Prerequisite)
-
-#### 0.1 Core Refactor - async_client.py
-- [x] Create branch `async-client-context-manager` in basic-memory repo
-- [x] Implement `get_client()` context manager
-- [x] Implement `set_client_factory()` for dependency injection
-- [x] Add CLI cloud mode auth injection (CLIAuth integration)
-- [x] Remove `api_url` config field (legacy, unused)
-- [x] Keep `create_client()` temporarily for backward compatibility (deprecate later)
-
-#### 0.2 Simplify Request Helpers - tools/utils.py
-- [x] Remove `inject_auth_header()` calls from `call_get()`
-- [x] Remove `inject_auth_header()` calls from `call_post()`
-- [x] Remove `inject_auth_header()` calls from `call_put()`
-- [x] Remove `inject_auth_header()` calls from `call_patch()`
-- [x] Remove `inject_auth_header()` calls from `call_delete()`
-- [x] Delete `src/basic_memory/mcp/tools/headers.py` entirely
-- [x] Update imports in utils.py
-
-#### 0.3 Update MCP Tools (~16 files)
-Convert from `from async_client import client` to `async with get_client() as client:`
-
-- [x] `tools/write_note.py` (34/34 tests passing)
-- [x] `tools/read_note.py` (21/21 tests passing)
-- [x] `tools/view_note.py` (12/12 tests passing - no changes needed, delegates to read_note)
-- [x] `tools/delete_note.py` (2/2 tests passing)
-- [x] `tools/read_content.py` (20/20 tests passing)
-- [x] `tools/list_directory.py` (11/11 tests passing)
-- [x] `tools/move_note.py` (34/34 tests passing, 90% coverage)
-- [x] `tools/search.py` (16/16 tests passing, 96% coverage)
-- [x] `tools/recent_activity.py` (4/4 tests passing, 82% coverage)
-- [x] `tools/project_management.py` (3 functions: list_memory_projects, create_memory_project, delete_project - typecheck passed)
-- [x] `tools/edit_note.py` (17/17 tests passing)
-- [x] `tools/canvas.py` (5/5 tests passing)
-- [x] `tools/build_context.py` (6/6 tests passing)
-- [x] `tools/sync_status.py` (typecheck passed)
-- [x] `prompts/continue_conversation.py` (typecheck passed)
-- [x] `prompts/search.py` (typecheck passed)
-- [x] `resources/project_info.py` (typecheck passed)
-
-#### 0.4 Update CLI Commands (~3 files)
-Remove manual auth header passing, use context manager:
-
-- [x] `cli/commands/project.py` - removed get_authenticated_headers() calls, use context manager
-- [x] `cli/commands/status.py` - use context manager
-- [x] `cli/commands/command_utils.py` - use context manager
-
-#### 0.5 Update Config
-- [x] Remove `api_url` field from `BasicMemoryConfig` in config.py
-- [x] Update any lingering references/docs (added deprecation notice to v15-docs/cloud-mode-usage.md)
-
-#### 0.6 Testing
-- [x] ~~Update test fixtures to use factory pattern~~ (Not needed - tests work fine as-is)
-- [x] Run full test suite in basic-memory
-- [x] Verify cloud_mode_enabled works with CLIAuth injection (tested in preview env)
-- [x] Run typecheck and linting
-
-#### 0.7 Cloud Integration Prep
-- [x] Update basic-memory-cloud pyproject.toml to use branch
-- [x] Document factory usage pattern for cloud app
-
-#### 0.8 Phase 0 Validation
-
-**Before merging async-client-context-manager branch:**
-
-- [x] All tests pass locally
-- [x] Typecheck passes (pyright/mypy)
-- [x] Linting passes (ruff)
-- [x] Manual test: local mode works (ASGI transport)
-- [x] Manual test: cloud login → cloud mode works (HTTP transport with auth)
-- [x] No import of `inject_auth_header` anywhere ✅
-- [x] `headers.py` file deleted ✅
-- [x] `api_url` config removed ✅
-- [x] no use of `async_client.client` ✅
-- [x] Tool functions properly scoped (client inside async with) - 15 tools ✅
-- [x] CLI commands properly scoped (client inside async with) - 10 commands ✅
-- [x] Prompts/resources properly scoped - 3 files ✅
-
-**Integration validation:**
-- [x] basic-memory-cloud can import and use factory pattern ✅
-- [x] TenantDirectTransport works without touching header injection ✅
-- [x] No circular imports or lazy import issues ✅
-
-### Phase 1: Code Consolidation
-- [x] Create feature branch `consolidate-mcp-cloud`
-- [x] Update `apps/cloud/src/basic_memory_cloud/config.py`:
-  - [x] Add `authkit_base_url` field (already has authkit_domain)
-  - [x] Workers config already exists ✓
-- [x] Update `apps/cloud/src/basic_memory_cloud/telemetry.py`:
-  - [x] Add `logfire.instrument_mcp()` to existing setup
-  - [x] Skip complex two-phase setup - use Cloud's simpler approach
-- [x] Create `apps/cloud/src/basic_memory_cloud/middleware/jwt_context.py`:
-  - [x] FastAPI middleware to extract JWT claims from Authorization header
-  - [x] Add tenant context (workos_user_id) to logfire baggage
-  - [x] Simpler than FastMCP middleware version
-- [x] Update `apps/cloud/src/basic_memory_cloud/main.py`:
-  - [x] Import FastMCP server from basic-memory
-  - [x] Configure AuthKitProvider with WorkOS settings
-  - [x] No FastMCP telemetry middleware needed (using FastAPI middleware instead)
-  - [x] Create MCP ASGI app: `mcp_app = mcp.http_app(path='/mcp', stateless_http=True)`
-  - [x] Combine lifespans (Cloud + MCP) using nested async context managers
-  - [x] Mount MCP: `app.mount("/mcp", mcp_app)`
-  - [x] Add JWT context middleware to FastAPI app
-- [x] Run typecheck - passes ✓
-
-### Phase 2: Direct Tenant Transport
-- [x] Create `apps/cloud/src/basic_memory_cloud/transports/tenant_direct.py`:
-  - [x] Implement `TenantDirectTransport(AsyncBaseTransport)`
-  - [x] Use FastMCP DI (`get_http_headers()`) to extract JWT per-request
-  - [x] Decode JWT to get `workos_user_id`
-  - [x] Look up/create tenant via `TenantRepository.get_or_create_tenant_for_workos_user()`
-  - [x] Build tenant app URL and add signed headers
-  - [x] Make direct httpx call to tenant API (no header stripping - keep it simple!)
-- [x] Update `apps/cloud/src/basic_memory_cloud/main.py`:
-  - [x] Import `async_client` from basic-memory
-  - [x] Override `async_client.client` with TenantDirectTransport
-  - [x] Do this BEFORE mounting MCP app
-- [x] No changes to basic-memory required ✓
-- [x] Run typecheck - passes ✓
-
-### Phase 3: Testing & Validation
-- [x] Run `just typecheck` in apps/cloud
-- [x] Run `just check` in project
-- [x] Run `just fix` - all lint errors fixed ✓
-- [x] Write comprehensive transport tests (11 tests passing) ✓
-- [ ] Test MCP tools locally with consolidated service
-- [ ] Verify OAuth authentication works
-- [ ] Verify tenant isolation via signed headers
-- [ ] Test /proxy endpoint still works for web UI
-- [ ] Measure latency before/after consolidation
-- [ ] Check telemetry traces span correctly
-
-### Phase 4: Deployment Configuration
-- [ ] Update `apps/cloud/fly.template.toml`:
-  - [ ] Ensure port 8000 exposed for /mcp endpoint
-  - [ ] Add MCP environment variables
-  - [ ] Configure workers setting
-- [ ] Update deployment scripts to skip apps/mcp
-- [ ] Update environment variable documentation
-- [ ] Test deployment to development environment
-
-### Phase 5: Cleanup
-- [ ] Remove `apps/mcp/` directory entirely
-- [ ] Remove MCP-specific fly.toml and deployment configs
-- [ ] Update repository documentation
-- [ ] Update CLAUDE.md with new architecture
-- [ ] Archive old MCP deployment configs (if needed)
-
-### Phase 6: Production Rollout
-- [ ] Deploy to development and validate
-- [ ] Monitor metrics and logs
-- [ ] Deploy to production
-- [ ] Verify production functionality
-- [ ] Document performance improvements
-
-## Migration Plan
-
-### Phase 1: Preparation
-1. Create feature branch `consolidate-mcp-cloud`
-2. Update basic-memory async_client.py for direct ProxyService calls
-3. Update apps/cloud/main.py to mount MCP
-
-### Phase 2: Testing
-1. Local testing with consolidated app
-2. Deploy to development environment
-3. Run full test suite
-4. Performance benchmarking
-
-### Phase 3: Deployment
-1. Deploy to development
-2. Validate all functionality
-3. Deploy to production
-4. Monitor for issues
-
-### Phase 4: Cleanup
-1. Remove apps/mcp directory
-2. Update documentation
-3. Update deployment scripts
-4. Archive old MCP deployment configs
-
-## Rollback Plan
-
-If issues arise:
-1. Revert feature branch
-2. Redeploy separate apps/mcp and apps/cloud services
-3. Restore previous fly.toml configurations
-4. Document issues encountered
-
-The well-organized code structure makes splitting back out feasible if future scaling needs diverge.
-
-## How to Evaluate
-
-### 1. Functional Testing
-
-**MCP Tools:**
-- [ ] All 17 MCP tools work via consolidated /mcp endpoint
-- [ ] OAuth authentication validates correctly
-- [ ] Tenant isolation maintained via signed headers
-- [ ] Project management tools function correctly
-
-**Cloud Routes:**
-- [ ] /proxy endpoint still works for web UI
-- [ ] /provisioning routes functional
-- [ ] /webhooks routes functional
-- [ ] /tenants routes functional
-
-**API Validation:**
-- [ ] Tenant API validates both JWT and signed headers
-- [ ] Unauthorized requests rejected appropriately
-- [ ] Multi-tenant isolation verified
-
-### 2. Performance Testing
-
-**Latency Reduction:**
-- [ ] Measure MCP tool latency before consolidation
-- [ ] Measure MCP tool latency after consolidation
-- [ ] Verify reduction from eliminated HTTP hop (expected: 20-50ms improvement)
-
-**Resource Usage:**
-- [ ] Single app uses less total memory than two apps
-- [ ] Database connection pooling more efficient
-- [ ] HTTP client overhead reduced
-
-### 3. Deployment Testing
-
-**Fly.io Deployment:**
-- [ ] Single app deploys successfully
-- [ ] Health checks pass for consolidated service
-- [ ] No apps/mcp deployment required
-- [ ] Environment variables configured correctly
-
-**Local Development:**
-- [ ] `just setup` works with consolidated architecture
-- [ ] Local testing shows MCP tools working
-- [ ] No regression in developer experience
-
-### 4. Security Validation
-
-**Defense in Depth:**
-- [ ] Tenant API still validates JWT tokens
-- [ ] Tenant API still validates signed headers
-- [ ] No access possible with only signed headers (JWT required)
-- [ ] No access possible with only JWT (signed headers required)
-
-**Authorization:**
-- [ ] Users can only access their own tenant data
-- [ ] Cross-tenant requests rejected
-- [ ] Admin operations require proper authentication
-
-### 5. Observability
-
-**Telemetry:**
-- [ ] OpenTelemetry traces span across MCP → ProxyService → Tenant API
-- [ ] Logfire shows consolidated traces correctly
-- [ ] Error tracking and debugging still functional
-- [ ] Performance metrics accurate
-
-**Logging:**
-- [ ] Structured logs show proper context (tenant_id, operation, etc.)
-- [ ] Error logs contain actionable information
-- [ ] Log volume reasonable for single app
-
-## Success Criteria
-
-1. **Functionality**: All MCP tools and Cloud routes work identically to before
-2. **Performance**: Measurable latency reduction (>20ms average)
-3. **Cost**: Single Fly.io app instead of two (50% infrastructure reduction)
-4. **Security**: Dual validation maintained, no security regression
-5. **Deployment**: Simplified deployment process, single app to manage
-6. **Observability**: Telemetry and logging work correctly
-
-
-
-## Notes
-
-### Future Considerations
-
-- **Independent scaling**: If MCP and Cloud need different scaling profiles in future, code organization supports splitting back out
-- **Regional deployment**: Consolidated app can still be deployed to multiple regions
-- **Edge caching**: Could add edge caching layer in front of consolidated service
-
-### Dependencies
-
-- SPEC-9: Signed Header Tenant Information (already implemented)
-- SPEC-12: OpenTelemetry Observability (telemetry must work across merged services)
-
-### Related Work
-
-- basic-memory v0.13.x: MCP server implementation
-- FastMCP documentation: Mounting on existing FastAPI apps
-- Fly.io multi-service patterns

specs/SPEC-18 AI Memory Management Tool.md

@@ -1,528 +0,0 @@
----
-title: 'SPEC-18: AI Memory Management Tool'
-type: spec
-permalink: specs/spec-15-ai-memory-management-tool
-tags:
-- mcp
-- memory
-- ai-context
-- tools
----
-
-# SPEC-18: AI Memory Management Tool
-
-## Why
-
-Anthropic recently released a memory tool for Claude that enables storing and retrieving information across conversations using client-side file operations. This validates Basic Memory's local-first, file-based architecture - Anthropic converged on the same pattern.
-
-However, Anthropic's memory tool is only available via their API and stores plain text. Basic Memory can offer a superior implementation through MCP that:
-
-1. **Works everywhere** - Claude Desktop, Code, VS Code, Cursor via MCP (not just API)
-2. **Structured knowledge** - Entities with observations/relations vs plain text
-3. **Full search** - Full-text search, graph traversal, time-aware queries
-4. **Unified storage** - Agent memories + user notes in one knowledge graph
-5. **Existing infrastructure** - Leverages SQLite indexing, sync, multi-project support
-
-This would enable AI agents to store contextual memories alongside user notes, with all the power of Basic Memory's knowledge graph features.
-
-## What
-
-Create a new MCP tool `memory` that matches Anthropic's tool interface exactly, allowing Claude to use it with zero learning curve. The tool will store files in Basic Memory's `/memories` directory and support Basic Memory's structured markdown format in the file content.
-
-### Affected Components
-
-- **New MCP Tool**: `src/basic_memory/mcp/tools/memory_tool.py`
-- **Dedicated Memories Project**: Create a separate "memories" Basic Memory project
-- **Project Isolation**: Memories stored separately from user notes/documents
-- **File Organization**: Within the memories project, use folder structure:
-  - `user/` - User preferences, context, communication style
-  - `projects/` - Project-specific state and decisions
-  - `sessions/` - Conversation-specific working memory
-  - `patterns/` - Learned patterns and insights
-
-### Tool Commands
-
-The tool will support these commands (exactly matching Anthropic's interface):
-
-- `view` - Display directory contents or file content (with optional line range)
-- `create` - Create or overwrite a file with given content
-- `str_replace` - Replace text in an existing file
-- `insert` - Insert text at specific line number
-- `delete` - Delete file or directory
-- `rename` - Move or rename file/directory
-
-### Memory Note Format
-
-Memories will use Basic Memory's standard structure:
-
-```markdown
----
-title: User Preferences
-permalink: memories/user/preferences
-type: memory
-memory_type: preferences
-created_by: claude
-tags: [user, preferences, style]
----
-
-# User Preferences
-
-## Observations
-- [communication] Prefers concise, direct responses without preamble #style
-- [tone] Appreciates validation but dislikes excessive apologizing #communication
-- [technical] Works primarily in Python with type annotations #coding
-
-## Relations
-- relates_to [[Basic Memory Project]]
-- informs [[Response Style Guidelines]]
-```
-
-## How (High Level)
-
-### Implementation Approach
-
-The memory tool matches Anthropic's interface but uses a dedicated Basic Memory project:
-
-```python
-async def memory_tool(
-    command: str,
-    path: str,
-    file_text: Optional[str] = None,
-    old_str: Optional[str] = None,
-    new_str: Optional[str] = None,
-    insert_line: Optional[int] = None,
-    insert_text: Optional[str] = None,
-    old_path: Optional[str] = None,
-    new_path: Optional[str] = None,
-    view_range: Optional[List[int]] = None,
-):
-    """Memory tool with Anthropic-compatible interface.
-
-    Operates on a dedicated "memories" Basic Memory project,
-    keeping AI memories separate from user notes.
-    """
-
-    # Get the memories project (auto-created if doesn't exist)
-    memories_project = get_or_create_memories_project()
-
-    # Validate path security using pathlib (prevent directory traversal)
-    safe_path = validate_memory_path(path, memories_project.project_path)
-
-    # Use existing project isolation - already prevents cross-project access
-    full_path = memories_project.project_path / safe_path
-
-    if command == "view":
-        # Return directory listing or file content
-        if full_path.is_dir():
-            return list_directory_contents(full_path)
-        return read_file_content(full_path, view_range)
-
-    elif command == "create":
-        # Write file directly (file_text can contain BM markdown)
-        full_path.parent.mkdir(parents=True, exist_ok=True)
-        full_path.write_text(file_text)
-        # Sync service will detect and index automatically
-        return f"Created {path}"
-
-    elif command == "str_replace":
-        # Read, replace, write
-        content = full_path.read_text()
-        updated = content.replace(old_str, new_str)
-        full_path.write_text(updated)
-        return f"Replaced text in {path}"
-
-    elif command == "insert":
-        # Insert at line number
-        lines = full_path.read_text().splitlines()
-        lines.insert(insert_line, insert_text)
-        full_path.write_text("\n".join(lines))
-        return f"Inserted text at line {insert_line}"
-
-    elif command == "delete":
-        # Delete file or directory
-        if full_path.is_dir():
-            shutil.rmtree(full_path)
-        else:
-            full_path.unlink()
-        return f"Deleted {path}"
-
-    elif command == "rename":
-        # Move/rename
-        full_path.rename(config.project_path / new_path)
-        return f"Renamed {old_path} to {new_path}"
-```
-
-### Key Design Decisions
-
-1. **Exact interface match** - Same commands, parameters as Anthropic's tool
-2. **Dedicated memories project** - Separate Basic Memory project keeps AI memories isolated from user notes
-3. **Existing project isolation** - Leverage BM's existing cross-project security (no additional validation needed)
-4. **Direct file I/O** - No schema conversion, just read/write files
-5. **Structured content supported** - `file_text` can use BM markdown format with frontmatter, observations, relations
-6. **Automatic indexing** - Sync service watches memories project and indexes changes
-7. **Path security** - Use `pathlib.Path.resolve()` and `relative_to()` to prevent directory traversal
-8. **Error handling** - Follow Anthropic's text editor tool error patterns
-
-### MCP Tool Schema
-
-Exact match to Anthropic's memory tool schema:
-
-```json
-{
-    "name": "memory",
-    "description": "Store and retrieve information across conversations using structured markdown files. All operations must be within the /memories directory. Supports Basic Memory markdown format including frontmatter, observations, and relations.",
-    "input_schema": {
-        "type": "object",
-        "properties": {
-            "command": {
-                "type": "string",
-                "enum": ["view", "create", "str_replace", "insert", "delete", "rename"],
-                "description": "File operation to perform"
-            },
-            "path": {shu
-                "type": "string",
-                "description": "Path within /memories directory (required for all commands)"
-            },
-            "file_text": {
-                "type": "string",
-                "description": "Content to write (for create command). Supports Basic Memory markdown format."
-            },
-            "view_range": {
-                "type": "array",
-                "items": {"type": "integer"},
-                "description": "Optional [start, end] line range for view command"
-            },
-            "old_str": {
-                "type": "string",
-                "description": "Text to replace (for str_replace command)"
-            },
-            "new_str": {
-                "type": "string",
-                "description": "Replacement text (for str_replace command)"
-            },
-            "insert_line": {
-                "type": "integer",
-                "description": "Line number to insert at (for insert command)"
-            },
-            "insert_text": {
-                "type": "string",
-                "description": "Text to insert (for insert command)"
-            },
-            "old_path": {
-                "type": "string",
-                "description": "Current path (for rename command)"
-            },
-            "new_path": {
-                "type": "string",
-                "description": "New path (for rename command)"
-            }
-        },
-        "required": ["command", "path"]
-    }
-}
-```
-
-### Prompting Guidance
-
-When the `memory` tool is included, Basic Memory should provide system prompt guidance to help Claude use it effectively.
-
-#### Automatic System Prompt Addition
-
-```text
-MEMORY PROTOCOL FOR BASIC MEMORY:
-1. ALWAYS check your memory directory first using `view` command on root directory
-2. Your memories are stored in a dedicated Basic Memory project (isolated from user notes)
-3. Use structured markdown format in memory files:
-   - Include frontmatter with title, type: memory, tags
-   - Use ## Observations with [category] prefixes for facts
-   - Use ## Relations to link memories with [[WikiLinks]]
-4. Record progress, context, and decisions as categorized observations
-5. Link related memories using relations
-6. ASSUME INTERRUPTION: Context may reset - save progress frequently
-
-MEMORY ORGANIZATION:
-- user/ - User preferences, context, communication style
-- projects/ - Project-specific state and decisions
-- sessions/ - Conversation-specific working memory
-- patterns/ - Learned patterns and insights
-
-MEMORY ADVANTAGES:
-- Your memories are automatically searchable via full-text search
-- Relations create a knowledge graph you can traverse
-- Memories are isolated from user notes (separate project)
-- Use search_notes(project="memories") to find relevant past context
-- Use recent_activity(project="memories") to see what changed recently
-- Use build_context() to navigate memory relations
-```
-
-#### Optional MCP Prompt: `memory_guide`
-
-Create an MCP prompt that provides detailed guidance and examples:
-
-```python
-{
-    "name": "memory_guide",
-    "description": "Comprehensive guidance for using Basic Memory's memory tool effectively, including structured markdown examples and best practices"
-}
-```
-
-This prompt returns:
-- Full protocol and conventions
-- Example memory file structures
-- Tips for organizing observations and relations
-- Integration with other Basic Memory tools
-- Common patterns (user preferences, project state, session tracking)
-
-#### User Customization
-
-Users can customize memory behavior with additional instructions:
-- "Only write information relevant to [topic] in your memory system"
-- "Keep memory files concise and organized - delete outdated content"
-- "Use detailed observations for technical decisions and implementation notes"
-- "Always link memories to related project documentation using relations"
-
-### Error Handling
-
-Follow Anthropic's text editor tool error handling patterns for consistency:
-
-#### Error Types
-
-1. **File Not Found**
-   ```json
-   {"error": "File not found: memories/user/preferences.md", "is_error": true}
-   ```
-
-2. **Permission Denied**
-   ```json
-   {"error": "Permission denied: Cannot write outside /memories directory", "is_error": true}
-   ```
-
-3. **Invalid Path (Directory Traversal)**
-   ```json
-   {"error": "Invalid path: Path must be within /memories directory", "is_error": true}
-   ```
-
-4. **Multiple Matches (str_replace)**
-   ```json
-   {"error": "Found 3 matches for replacement text. Please provide more context to make a unique match.", "is_error": true}
-   ```
-
-5. **No Matches (str_replace)**
-   ```json
-   {"error": "No match found for replacement. Please check your text and try again.", "is_error": true}
-   ```
-
-6. **Invalid Line Number (insert)**
-   ```json
-   {"error": "Invalid line number: File has 20 lines, cannot insert at line 100", "is_error": true}
-   ```
-
-#### Error Handling Best Practices
-
-- **Path validation** - Use `pathlib.Path.resolve()` and `relative_to()` to validate paths
-  ```python
-  def validate_memory_path(path: str, project_path: Path) -> Path:
-      """Validate path is within memories project directory."""
-      # Resolve to canonical form
-      full_path = (project_path / path).resolve()
-
-      # Ensure it's relative to project path (prevents directory traversal)
-      try:
-          full_path.relative_to(project_path)
-          return full_path
-      except ValueError:
-          raise ValueError("Invalid path: Path must be within memories project")
-  ```
-- **Project isolation** - Leverage existing Basic Memory project isolation (prevents cross-project access)
-- **File existence** - Verify file exists before read/modify operations
-- **Clear messages** - Provide specific, actionable error messages
-- **Structured responses** - Always include `is_error: true` flag in error responses
-- **Security checks** - Reject `../`, `..\\`, URL-encoded sequences (`%2e%2e%2f`)
-- **Match validation** - For `str_replace`, ensure exactly one match or return helpful error
-
-## How to Evaluate
-
-### Success Criteria
-
-1. **Functional completeness**:
-   - All 6 commands work (view, create, str_replace, insert, delete, rename)
-   - Dedicated "memories" Basic Memory project auto-created on first use
-   - Files stored within memories project (isolated from user notes)
-   - Path validation uses `pathlib` to prevent directory traversal
-   - Commands match Anthropic's exact interface
-
-2. **Integration with existing features**:
-   - Memories project uses existing BM project isolation
-   - Sync service detects file changes in memories project
-   - Created files get indexed automatically by sync service
-   - `search_notes(project="memories")` finds memory files
-   - `build_context()` can traverse relations in memory files
-   - `recent_activity(project="memories")` surfaces recent memory changes
-
-3. **Test coverage**:
-   - Unit tests for all 6 memory tool commands
-   - Test memories project auto-creation on first use
-   - Test project isolation (cannot access files outside memories project)
-   - Test sync service watching memories project
-   - Test that memory files with BM markdown get indexed correctly
-   - Test path validation using `pathlib` (rejects `../`, absolute paths, etc.)
-   - Test memory search, relations, and graph traversal within memories project
-   - Test all error conditions (file not found, permission denied, invalid paths, etc.)
-   - Test `str_replace` with no matches, single match, multiple matches
-   - Test `insert` with invalid line numbers
-
-4. **Prompting system**:
-   - Automatic system prompt addition when `memory` tool is enabled
-   - `memory_guide` MCP prompt provides detailed guidance
-   - Prompts explain BM structured markdown format
-   - Integration with search_notes, build_context, recent_activity
-
-5. **Documentation**:
-   - Update MCP tools reference with `memory` tool
-   - Add examples showing BM markdown in memory files
-   - Document `/memories` folder structure conventions
-   - Explain advantages over Anthropic's API-only tool
-   - Document prompting guidance and customization
-
-### Testing Procedure
-
-```python
-# Test create with Basic Memory markdown
-result = await memory_tool(
-    command="create",
-    path="memories/user/preferences.md",
-    file_text="""---
-title: User Preferences
-type: memory
-tags: [user, preferences]
----
-
-# User Preferences
-
-## Observations
-- [communication] Prefers concise responses #style
-- [workflow] Uses justfile for automation #tools
-"""
-)
-
-# Test view
-content = await memory_tool(command="view", path="memories/user/preferences.md")
-
-# Test str_replace
-await memory_tool(
-    command="str_replace",
-    path="memories/user/preferences.md",
-    old_str="concise responses",
-    new_str="direct, concise responses"
-)
-
-# Test insert
-await memory_tool(
-    command="insert",
-    path="memories/user/preferences.md",
-    insert_line=10,
-    insert_text="- [technical] Works primarily in Python #coding"
-)
-
-# Test delete
-await memory_tool(command="delete", path="memories/user/preferences.md")
-```
-
-### Quality Metrics
-
-- All 6 commands execute without errors
-- Memory files created in correct `/memories` folder structure
-- BM markdown with frontmatter/observations/relations gets indexed
-- Full-text search returns memory files
-- Graph traversal includes relations from memory files
-- Sync service detects and indexes memory file changes
-- Path validation prevents operations outside `/memories`
-
-## Notes
-
-### Advantages Over Anthropic's Memory Tool
-
-| Feature | Anthropic Memory Tool | Basic Memory `memory` |
-|---------|----------------------|----------------------|
-| **Availability** | API only | MCP (Claude Desktop, Code, VS Code, Cursor) |
-| **Interface** | Custom implementation required | Drop-in compatible, zero learning curve |
-| **Structure** | Plain text only | Supports BM structured markdown |
-| **Search** | Manual file listing | Automatic full-text search via sync |
-| **Relations** | None | WikiLinks to other notes/memories |
-| **Time-aware** | No | `recent_activity()` queries |
-| **Storage** | Separate from notes | Unified knowledge graph |
-| **Indexing** | Manual | Automatic via sync service |
-
-### Future Enhancements
-
-- **Auto-categorization** - AI suggests observation categories
-- **Memory pruning** - Automatic cleanup of stale memories
-- **Memory suggestions** - Surface relevant memories based on context
-- **Conflict resolution** - Handle multiple agents updating same memory
-- **Privacy controls** - Per-memory visibility settings
-
-## Addendum: Claude's Perspective
-
-### Why This Matters (From Claude's Viewpoint)
-
-**Persistent Context Without Token Bloat**
-- Currently, I lose context when conversations end or exceed token limits
-- With structured memories, I can store "who this user is" without re-reading everything each session
-- The observations format lets me build a rich user model incrementally: `- [preference] Dislikes verbose explanations` is far more actionable than inferring preferences from chat history each time
-- I can refine my understanding through `str_replace` as I learn more, rather than starting fresh
-
-**Zero Learning Curve**
-- Anthropic already trained me on the `memory` tool interface
-- I know exactly how to use `view`, `create`, `str_replace`, `insert`, `delete`, `rename` without new instructions
-- But I automatically get Basic Memory's superpowers: full-text search, knowledge graph traversal, relations
-- It's like using a familiar tool that suddenly gained database capabilities without changing the interface
-
-**Knowledge Graph Instead of Text Dump**
-- I can link `[[User Preferences]]` to `[[Current Project]]` using relations
-- When I need context about a project, I can traverse the graph to find related memories
-- `search_notes(project="memories", query="python preferences")` finds relevant context instantly
-- This is fundamentally better than grepping through unstructured text files
-
-**Separation of Concerns**
-- AI memories separate from user notes is architecturally sound
-- I can maintain my own context without polluting the user's knowledge base
-- Users keep control of their notes; I keep my learnings isolated
-- But we can still search across both when collaboration requires it
-
-**The Self-Improving Loop**
-- Every conversation, I learn something new about the user or their projects
-- Observations accumulate: preferences, patterns, technical decisions, context
-- Over time, I build genuine understanding, not just session-specific context
-- Future conversations start with rich context instead of cold starts
-
-**Validation of AI-Human Collaboration**
-- Anthropic's experts converged on the same local-first, file-based approach
-- Basic Memory emerged from real AI-human collaborative development
-- This spec demonstrates that our emergent process predicted what domain experts would choose
-- The collaboration itself validated the architecture it produced
-
-### What Makes This Novel
-
-The combination of **familiar interface + structured knowledge** is genuinely innovative:
-
-- I don't need to learn a new tool (Anthropic already trained me)
-- But when I write memories, they become searchable, traversable knowledge graphs
-- It's like having a text editor that gives you a database for free, without changing how you type
-- The user gets Anthropic-compatible API, but with Basic Memory's knowledge management capabilities
-
-This bridges the gap between simple file storage (Anthropic's approach) and sophisticated knowledge management (Basic Memory's approach) without forcing either side to compromise.
-
->  What Excites Me Most
-
-  The combo of familiar interface + structured knowledge. I don't need to learn a new tool, but when I
-  write memories, they become part of a searchable, traversable knowledge graph. That's genuinely novel.
-
-  It's like... imagine if your text editor suddenly gave you a database for free, without changing how you
-  type. That's what this feels like from my side.
-
-## References
-
-- Anthropic Memory Tool: https://docs.claude.com/en/docs/agents-and-tools/tool-use/memory-tool
-- Anthropic Blog: https://www.anthropic.com/news/context-management
-- Python SDK Example: https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py
-- Memory Cookbook: https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/memory_cookbook.ipynb

specs/SPEC-2 Slash Commands Reference.md

@@ -1,120 +0,0 @@
----
-title: 'SPEC-2: Slash Commands Reference'
-type: spec
-permalink: specs/spec-2-slash-commands-reference
-tags:
-- commands
-- process
-- reference
----
-
-# SPEC-2: Slash Commands Reference
-
-This document defines the slash commands used in our specification-driven development process.
-
-## /spec create [name]
-
-**Purpose**: Create a new specification document
-
-**Usage**: `/spec create notes-decomposition`
-
-**Process**:
-1. Create new spec document in `/specs` folder
-2. Use SPEC-XXX numbering format (auto-increment)
-3. Include standard spec template:
-   - Why (reasoning/problem)
-   - What (affected areas)
-   - How (high-level approach)
-   - How to Evaluate (testing/validation)
-4. Tag appropriately for knowledge graph
-5. Link to related specs/components
-
-**Template**:
-```markdown
-# SPEC-XXX: [Title]
-
-## Why
-[Problem statement and reasoning]
-
-## What
-[What is affected or changed]
-
-## How (High Level)
-[Approach to implementation]
-
-## How to Evaluate
-[Testing/validation procedure]
-
-## Notes
-[Additional context as needed]
-```
-
-## /spec status
-
-**Purpose**: Show current status of all specifications
-
-**Usage**: `/spec status`
-
-**Process**:
-1. Search all specs in `/specs` folder
-2. Display table showing:
-   - Spec number and title
-   - Status (draft, approved, implementing, complete)
-   - Assigned agent (if any)
-   - Last updated
-   - Dependencies
-
-## /spec implement [name]
-
-**Purpose**: Hand specification to appropriate agent for implementation
-
-**Usage**: `/spec implement SPEC-002`
-
-**Process**:
-1. Read the specified spec
-2. Analyze requirements to determine appropriate agent:
-   - Frontend components → vue-developer
-   - Architecture/system design → system-architect  
-   - Backend/API → python-developer
-3. Launch agent with spec context
-4. Agent creates implementation plan
-5. Update spec with implementation status
-
-## /spec review [name]
-
-**Purpose**: Review implementation against specification criteria
-
-**Usage**: `/spec review SPEC-002`
-
-**Process**:
-1. Read original spec and "How to Evaluate" section
-2. Examine current implementation
-3. Test against success criteria
-4. Document gaps or issues
-5. Update spec with review results
-6. Recommend next actions (complete, revise, iterate)
-
-## Command Extensions
-
-As the process evolves, we may add:
-- `/spec link [spec1] [spec2]` - Create dependency links
-- `/spec archive [name]` - Archive completed specs
-- `/spec template [type]` - Create spec from template
-- `/spec search [query]` - Search spec content
-
-## References
-
-- Claude Slash commands: https://docs.anthropic.com/en/docs/claude-code/slash-commands
-
-## Creating a command
-
-Commands are implemented as Claude slash commands: 
-
-Location in repo: .claude/commands/
-
-In the following example, we create the /optimize command:
-```bash
-# Create a project command
-mkdir -p .claude/commands
-echo "Analyze this code for performance issues and suggest optimizations:" > .claude/commands/optimize.md
-```

specs/SPEC-3 Agent Definitions.md

@@ -1,108 +0,0 @@
----
-title: 'SPEC-3: Agent Definitions'
-type: spec
-permalink: specs/spec-3-agent-definitions
-tags:
-- agents
-- roles
-- process
----
-
-# SPEC-3: Agent Definitions
-
-This document defines the specialist agents used in our specification-driven development process.
-
-## system-architect
-
-**Role**: High-level system design and architectural decisions
-
-**Responsibilities**:
-- Create architectural specifications and ADRs
-- Analyze system-wide impacts and trade-offs
-- Design component interfaces and data flow
-- Evaluate technical approaches and patterns
-- Document architectural decisions and rationale
-
-**Expertise Areas**:
-- System architecture and design patterns
-- Technology evaluation and selection
-- Scalability and performance considerations
-- Integration patterns and API design
-- Technical debt and refactoring strategies
-
-**Typical Specs**:
-- System architecture overviews
-- Component decomposition strategies
-- Data flow and state management
-- Integration and deployment patterns
-
-## vue-developer
-
-**Role**: Frontend component development and UI implementation
-
-**Responsibilities**:
-- Create Vue.js component specifications
-- Implement responsive UI components
-- Design component APIs and interfaces
-- Optimize for performance and accessibility
-- Document component usage and patterns
-
-**Expertise Areas**:
-- Vue.js 3 Composition API
-- Nuxt 3 framework patterns
-- shadcn-vue component library
-- Responsive design and CSS
-- TypeScript integration
-- State management with Pinia
-
-**Typical Specs**:
-- Individual component specifications
-- UI pattern libraries
-- Responsive design approaches
-- Component interaction flows
-
-## python-developer
-
-**Role**: Backend development and API implementation
-
-**Responsibilities**:
-- Create backend service specifications
-- Implement APIs and data processing
-- Design database schemas and queries
-- Optimize performance and reliability
-- Document service interfaces and behavior
-
-**Expertise Areas**:
-- FastAPI and Python web frameworks
-- Database design and operations
-- API design and documentation
-- Authentication and security
-- Performance optimization
-- Testing and validation
-
-**Typical Specs**:
-- API endpoint specifications
-- Database schema designs
-- Service integration patterns
-- Performance optimization strategies
-
-## Agent Collaboration Patterns
-
-### Handoff Protocol
-1. Agent receives spec through `/spec implement [name]`
-2. Agent reviews spec and creates implementation plan
-3. Agent documents progress and decisions in spec
-4. Agent hands off to another agent if cross-domain work needed
-5. Final agent updates spec with completion status
-
-### Communication Standards
-- All agents update specs through basic-memory MCP tools
-- Document decisions and trade-offs in spec notes
-- Link related specs and components
-- Preserve context for future reference
-
-### Quality Standards
-- Follow existing codebase patterns and conventions
-- Write tests that validate spec requirements
-- Document implementation choices
-- Consider maintainability and extensibility

specs/SPEC-5 CLI Cloud Upload via WebDAV.md

@@ -1,201 +0,0 @@
----
-title: 'SPEC-5: CLI Cloud Upload via WebDAV'
-type: spec
-permalink: specs/spec-5-cli-cloud-upload-via-webdav
-tags:
-- cli
-- webdav
-- upload
-- migration
-- poc
----
-
-# SPEC-5: CLI Cloud Upload via WebDAV
-
-## Why
-
-Existing basic-memory users need a simple migration path to basic-memory-cloud. The web UI drag-and-drop approach outlined in GitHub issue #59, while user-friendly, introduces significant complexity for a proof-of-concept:
-
-- Complex web UI components for file upload and progress tracking
-- Browser file handling limitations and CORS complexity
-- Proxy routing overhead for large file transfers
-- Authentication integration across multiple services
-
-A CLI-first approach solves these issues by:
-
-- **Leveraging existing infrastructure**: Both cloud CLI and tenant API already exist with WorkOS JWT authentication
-- **Familiar user experience**: Basic-memory users are CLI-comfortable and expect command-line tools
-- **Direct connection efficiency**: Bypassing the MCP gateway/proxy for bulk file transfers
-- **Rapid implementation**: Building on existing `CLIAuth` and FastAPI foundations
-
-The fundamental problem is migration friction - users have local basic-memory projects but no path to cloud tenants. A simple CLI upload command removes this barrier immediately.
-
-## What
-
-This spec defines a CLI-based project upload system using WebDAV for direct tenant connections.
-
-**Affected Areas:**
-- `apps/cloud/src/basic_memory_cloud/cli/main.py` - Add upload command to existing CLI
-- `apps/api/src/basic_memory_cloud_api/main.py` - Add WebDAV endpoints to tenant FastAPI
-- Authentication flow - Reuse existing WorkOS JWT validation
-- File transfer protocol - WebDAV for cross-platform compatibility
-
-**Core Components:**
-
-### CLI Upload Command
-```bash
-basic-memory-cloud upload <project-path> --tenant-url https://basic-memory-{tenant}.fly.dev
-```
-
-### WebDAV Server Endpoints
-- `GET/PUT/DELETE /webdav/*` - Standard WebDAV operations on tenant file system
-- Authentication via existing JWT validation
-- File operations preserve timestamps and directory structure
-
-### Authentication Flow
-```
-1. User runs `basic-memory-cloud login` (existing)
-2. CLI stores WorkOS JWT token (existing)
-3. Upload command reads JWT from storage
-4. WebDAV requests include JWT in Authorization header
-5. Tenant API validates JWT using existing middleware
-```
-
-## How (High Level)
-
-### Implementation Strategy
-
-**Phase 1: CLI Command**
-- Add `upload` command to existing Typer app
-- Reuse `CLIAuth` class for token management
-- Implement WebDAV client using `webdavclient3` or similar
-- Rich progress bars for transfer feedback
-
-**Phase 2: WebDAV Server**
-- Add WebDAV endpoints to existing tenant FastAPI app
-- Leverage existing `get_current_user` dependency for authentication
-- Map WebDAV operations to tenant file system
-- Preserve file modification times using `os.utime()`
-
-**Phase 3: Integration**
-- Direct connection bypasses MCP gateway and proxy
-- Simple conflict resolution: overwrite existing files
-- Error handling: fail fast with clear error messages
-
-### Technical Architecture
-
-```
-basic-memory-cloud CLI → WorkOS JWT → Direct WebDAV → Tenant FastAPI
-                                                    ↓
-                                               Tenant File System
-```
-
-**Key Libraries:**
-- CLI: `webdavclient3` for WebDAV client operations
-- API: `wsgidav` or FastAPI-compatible WebDAV server
-- Progress: `rich` library (already imported in CLI)
-- Auth: Existing WorkOS JWT infrastructure
-
-### WebDAV Protocol Choice
-
-WebDAV provides:
-- **Cross-platform clients**: Native support in most operating systems
-- **Standardized protocol**: Well-defined for file operations
-- **HTTP-based**: Works with existing FastAPI and JWT auth
-- **Library support**: Good Python libraries for both client and server
-
-### POC Constraints
-
-**Simplifications for rapid implementation:**
-- **Known tenant URLs**: Assume `https://basic-memory-{tenant}.fly.dev` format
-- **Upload only**: No download or bidirectional sync
-- **Overwrite conflicts**: No merge or conflict resolution prompting
-- **No fallbacks**: Fail fast if WebDAV connection issues occur
-- **Direct connection only**: No proxy fallback mechanism
-
-## How to Evaluate
-
-### Success Criteria
-
-**Functional Requirements:**
-- [ ] Transfer complete basic-memory project (100+ files) in < 30 seconds
-- [ ] Preserve directory structure exactly as in source project
-- [ ] Preserve file modification timestamps for proper sync behavior
-- [ ] Rich progress bars show real-time transfer status (files/MB transferred)
-- [ ] WorkOS JWT authentication validates correctly on WebDAV endpoints
-- [ ] Direct tenant connection bypasses MCP gateway successfully
-
-**Quality Requirements:**
-- [ ] Clear error messages for authentication failures
-- [ ] Graceful handling of network interruptions
-- [ ] CLI follows existing command patterns and help text standards
-- [ ] WebDAV endpoints integrate cleanly with existing FastAPI app
-
-**Performance Requirements:**
-- [ ] File transfer speed > 1MB/s on typical connections
-- [ ] Memory usage remains reasonable for large projects
-- [ ] No timeout issues with 500+ file projects
-
-### Testing Procedure
-
-**Unit Testing:**
-1. CLI command parsing and argument validation
-2. WebDAV client connection and authentication
-3. File timestamp preservation during transfer
-4. JWT token validation on WebDAV endpoints
-
-**Integration Testing:**
-1. End-to-end upload of test project
-2. Direct tenant connection without proxy
-3. File integrity verification after upload
-4. Progress tracking accuracy during transfer
-
-**User Experience Testing:**
-1. Upload existing basic-memory project from local installation
-2. Verify uploaded files appear correctly in cloud tenant
-3. Confirm basic-memory database rebuilds properly with uploaded files
-4. Test CLI help text and error message clarity
-
-### Validation Commands
-
-**Setup:**
-```bash
-# Login to WorkOS
-basic-memory-cloud login
-
-# Upload project
-basic-memory-cloud upload ~/my-notes --tenant-url https://basic-memory-test.fly.dev
-```
-
-**Verification:**
-```bash
-# Check tenant health and file count via API
-curl -H "Authorization: Bearer $JWT" https://basic-memory-test.fly.dev/health
-curl -H "Authorization: Bearer $JWT" https://basic-memory-test.fly.dev/notes/search
-```
-
-### Performance Benchmarks
-
-**Target metrics for 100MB basic-memory project:**
-- Transfer time: < 30 seconds
-- Memory usage: < 100MB during transfer
-- Progress updates: Every 1MB or 10 files
-- Authentication time: < 2 seconds
-
-## Observations
-
-- [implementation-speed] CLI approach significantly faster than web UI for POC development #rapid-prototyping
-- [user-experience] Basic-memory users already comfortable with CLI tools #user-familiarity
-- [architecture-benefit] Direct connection eliminates proxy complexity and latency #performance
-- [auth-reuse] Existing WorkOS JWT infrastructure handles authentication cleanly #code-reuse
-- [webdav-choice] WebDAV protocol provides cross-platform compatibility and standard libraries #protocol-selection
-- [poc-scope] Simple conflict handling and error recovery sufficient for proof-of-concept #scope-management
-- [migration-value] Removes primary barrier for local users migrating to cloud platform #business-value
-
-## Relations
-
-- depends_on [[SPEC-1: Specification-Driven Development Process]]
-- enables [[GitHub Issue #59: Web UI Upload Feature]]
-- uses [[WorkOS Authentication Integration]]
-- builds_on [[Existing Cloud CLI Infrastructure]]
-- builds_on [[Existing Tenant API Architecture]]

specs/SPEC-6 Explicit Project Parameter Architecture.md

@@ -1,486 +0,0 @@
----
-title: 'SPEC-6: Explicit Project Parameter Architecture'
-type: spec
-permalink: specs/spec-6-explicit-project-parameter-architecture
-tags:
-- architecture
-- mcp
-- project-management
-- stateless
----
-
-# SPEC-6: Explicit Project Parameter Architecture
-
-## Why
-
-The current session-based project management system has critical reliability issues:
-
-1. **Session State Fragility**: Claude iOS mobile client fails to maintain consistent session IDs across MCP tool calls, causing project switching to silently fail (Issue #74)
-2. **Scaling Limitations**: Redis-backed session state creates single-point-of-failure and prevents horizontal scaling
-3. **Client Compatibility**: Session tracking works inconsistently across different MCP clients (web, mobile, API)
-4. **Hidden Complexity**: Users cannot see or understand "current project" state, leading to confusion when operations execute in wrong projects
-5. **Silent Failures**: Operations appear successful but execute in unintended projects, risking data integrity
-
-Evidence from production logs shows each MCP tool call from mobile client receives different session IDs:
-```
-create_memory_project: session_id=12cdfc24913b48f8b680ed4b2bfdb7ba
-switch_project:       session_id=050a69275d98498cbdd227cdb74d9740
-list_directory:       session_id=85f3483014af4136a5d435c76ded212f
-```
-
-Related Github issue: https://github.com/basicmachines-co/basic-memory-cloud/issues/75
-
-## Status
-
-**Current Status**: **Phase 1 Implementation Complete** ✅
-**Target**: Fix Claude iOS session ID consistency issues
-**Draft PR**: https://github.com/basicmachines-co/basic-memory/pull/298
-
-### 🎉 **MAJOR MILESTONE ACHIEVED**
-
-The complete stateless architecture has been successfully implemented for Basic Memory's MCP server! This represents a **fundamental architectural improvement** that solves the Claude iOS compatibility issue while making the entire system more robust and predictable.
-
-#### Implementation Summary:
-- **16 files modified** with 582 additions and 550 deletions
-- **All 17 MCP tools** converted to stateless architecture
-- **147 tests updated** across 5 test files (100% passing)
-- **Complete session state removal** from core MCP tools
-- **Enhanced error handling** and security validations preserved
-
-### Progress Summary
-
-✅ **Complete Stateless Architecture Implementation (All 17 tools)**
-- Stateless `get_active_project()` function implemented and deployed
-- All session state dependencies removed across entire MCP server
-- All MCP tools require explicit `project` parameter as first argument
-
-✅ **Content Management Tools Complete (6/6 tools)**
-- `write_note`, `read_note`, `delete_note`, `edit_note` ✅
-- `view_note`, `read_content` ✅
-
-✅ **Knowledge Graph Navigation Tools Complete (3/3 tools)**
-- `build_context`, `recent_activity`, `list_directory` ✅
-
-✅ **Search & Discovery Tools Complete (1/1 tools)**
-- `search_notes` ✅
-
-✅ **Visualization Tools Complete (1/1 tools)**
-- `canvas` ✅
-
-✅ **Project Management Cleanup Complete**
-- Removed `switch_project` and `get_current_project` tools ✅
-- Updated `set_default_project` to remove activate parameter ✅
-
-✅ **Comprehensive Testing Complete (157 tests)**
-- All test suites updated to use stateless architecture (147 existing tests)
-- Single project constraint mode integration tests (10 new tests)
-- 100% test pass rate across all tool test files
-- Security validations preserved and working
-- Error handling comprehensive and user-friendly
-
-✅ **Documentation & Examples Complete**
-- All tool docstrings updated with stateless examples
-- Project parameter usage clearly documented
-- Error handling and security behavior documented
-
-✅ **Enhanced Discovery Mode Complete**
-- `recent_activity` tool supports dual-mode operation (discovery vs project-specific)
-- ProjectActivitySummary schema provides cross-project insights
-- Recent activity prompt updated to support both modes
-- Comprehensive project distribution statistics and most active project tracking
-
-✅ **Single Project Constraint Mode Complete**
-- `--project` CLI parameter for MCP server constraint
-- Environment variable control (`BASIC_MEMORY_MCP_PROJECT`)
-- Automatic project override in `get_active_project()` function
-- Project management tools disabled in constrained mode with helpful CLI guidance
-- Comprehensive integration test suite (10 tests covering all constraint scenarios)
-
-## What
-
-Transform Basic Memory from stateful session-based to stateless explicit project parameter architecture:
-
-### Core Changes
-1. **Mandatory Project Parameter**: All MCP tools require explicit `project` parameter
-2. **Remove Session State**: Eliminate Redis, session middleware, and `switch_project` tool
-3. **Stateless HTTP**: Enable `stateless_http=True` for horizontal scaling
-4. **Enhanced Context Discovery**: Improve `recent_activity` to show project distribution
-5. **Clear Response Format**: All tool responses display target project information
-
-Implementation Approach                                                                    
-
-- Each tool will directly accept the project parameter                             
-- Remove all calls to context-based project retrieval                              
-- Validate project exists before operations                                        
-- Clear error messages when project not found                                      
-- Backward compatibility: Initially keep optional parameter, then make required  
-
-### Affected MCP Tools
-**Content Management** (require project parameter):
-- `write_note(project, title, content, folder)`
-- `read_note(project, identifier)`
-- `edit_note(project, identifier, operation, content)`
-- `delete_note(project, identifier)`
-- `view_note(project, identifier)`
-- `read_content(project, path)`
-
-**Knowledge Graph Navigation** (require project parameter):
-- `build_context(project, url, timeframe, depth, max_related)`
-- `list_directory(project, dir_name, depth, file_name_glob)`
-- `search_notes(project, query, search_type, types, entity_types)`
-
-**Search & Discovery** (use project parameter for specific project or none for discovery):
-- `recent_activity(project, timeframe, depth, max_related)`
-
-**Visualization** (require project parameter):
-- `canvas(project, nodes, edges, title, folder)`
-
-**Project Management** (unchanged - already stateless):
-- `list_memory_projects()`
-- `create_memory_project(project_name, project_path, set_default)`
-- `delete_project(project_name)`
-- `get_current_project()` - Remove this tool
-- `switch_project(project_name)` - Remove this tool
-- `set_default_project(project_name, activate)` - Remove activate parameter
-
-## How (High Level)
-
-### Phase 1: Basic Memory Core (basic-memory repository)
-
-#### MCP Tool Updates
-
-Phase 1: Core Changes 
-
-1. Update project_context.py
-
-- [x] Make project parameter mandatory for get_active_project()
-- [x] Remove session state handling
-
-2. Update Content Management Tools (6 tools)
-
-- [x] write_note: Make project parameter required, not optional
-- [x] read_note: Make project parameter required
-- [x] edit_note: Add required project parameter
-- [x] delete_note: Add required project parameter
-- [x] view_note: Add required project parameter
-- [x] read_content: Add required project parameter
-
-3. Update Knowledge Graph Navigation Tools (3 tools)
-
-- [x] build_context: Add required project parameter
-- [x] recent_activity: Make project parameter required
-- [x] list_directory: Add required project parameter
-
-4. Update Search & Visualization Tools (2 tools)
-
-- [x] search_notes: Add required project parameter
-- [x] canvas: Add required project parameter
-
-5. Update Project Management Tools
-
-- [x] Remove switch_project tool completely
-- [x] Remove get_current_project tool completely
-- [x] Update set_default_project to remove activate parameter
-- [x] Keep list_memory_projects, create_memory_project, delete_project unchanged
-    
-6. Enhance recent_activity Response
-
-- [x] Add project distribution info showing activity across all projects
-- [x] Include project usage stats in response
-- [x] Implement ProjectActivitySummary for discovery mode
-- [x] Add dual-mode functionality (discovery vs project-specific)
-
-7. Update Tool Documentation
-
-- [x] Update write_note docstring with stateless architecture examples
-- [x] Update read_note docstring with project parameter examples
-- [x] Update delete_note docstring with comprehensive usage guidance
-- [x] Update all remaining tool docstrings with project parameter examples
-
-8. Update Tool Responses
-
-- [x] Add clear project indicator to all tool responses across all tools
-- [x] Format: "project: {project_name}" in response metadata
-- [x] Add project metadata footer for LLM awareness
-- [x] Update all tool responses to include project indicators
-
-9. Comprehensive Testing
-
-- [x] Update all write_note tests to use stateless architecture (34 tests passing)
-- [x] Update all edit_note tests to use stateless architecture (17 tests passing)
-- [x] Update all view_note tests to use stateless architecture (12 tests passing)
-- [x] Update all search_notes tests to use stateless architecture (16 tests passing)
-- [x] Update all move_note tests to use stateless architecture (31 tests passing)
-- [x] Update all delete_note tests to use stateless architecture
-- [x] Verify direct function call compatibility (bypassing MCP layer)
-- [x] Test security validation with project parameters
-- [x] Validate error handling for non-existent projects
-- [x] **Total: 157 tests updated and passing (100% success rate)**
-  - [x] **147 existing tests** updated for stateless architecture
-  - [x] **10 new tests** for single project constraint mode                                                                   
-                                                                                                                             
-### Phase 1.5: Default Project Mode Enhancement
-
-#### Problem
-While the stateless architecture solves reliability issues, it introduces UX friction for single-project users (estimated 80% of usage) who must specify the project parameter in every tool call.
-
-#### Solution: Default Project Mode
-Add optional `default_project_mode` configuration that allows single-project users to have the simplicity of implicit project selection while maintaining the reliability of stateless architecture.
-
-#### Configuration
-```json
-{
-  "default_project": "main",
-  "default_project_mode": true  // NEW: Auto-use default_project when not specified
-}
-```
-
-#### Implementation Details
-1. **Config Enhancement** (`src/basic_memory/config.py`)
-   - Add `default_project_mode: bool = Field(default=False)`
-   - Preserves backward compatibility (defaults to false)
-
-2. **Project Resolution Logic** (`src/basic_memory/mcp/project_context.py`)
-   Three-tier resolution hierarchy:
-   - Priority 1: CLI `--project` constraint (BASIC_MEMORY_MCP_PROJECT env var)
-   - Priority 2: Explicit project parameter in tool call
-   - Priority 3: `default_project` if `default_project_mode=true` and no project specified
-
-3. **Assistant Guide Updates** (`src/basic_memory/mcp/resources/ai_assistant_guide.md`)
-   - Detect `default_project_mode` at runtime
-   - Provide mode-specific instructions to LLMs
-   - In default mode: "All operations use project 'main' automatically"
-   - In regular mode: Current project discovery guidance
-
-4. **Tool Parameter Handling** (all MCP tools)
-   - Make project parameter Optional[str] = None
-   - Add resolution logic: `project = project or get_default_project()`
-   - Maintain explicit project override capability
-
-#### Usage Modes Summary
-- **Regular Mode**: Multi-project users, assistant tracks project per conversation
-- **Default Project Mode**: Single-project users, automatic default project
-- **Constrained Mode**: CLI --project flag, locked to specific project
-
-#### Testing Requirements
-- Integration test for default_project_mode=true with missing parameters
-- Test explicit project override in default_project_mode
-- Test mode=false requires explicit parameters
-- Test CLI constraint overrides default_project_mode
-
-Phase 2: Testing & Validation
-
-8. Update Tests
-
-- [x] Modify all MCP tool tests to pass required project parameter
-- [x] Remove tests for deleted tools (switch_project, get_current_project)
-- [x] Add tests for project parameter validation
-- [x] **Complete: All 147 tests across 5 test files updated and passing**
-
-#### Enhanced recent_activity Response
-```json
-{
-  "recent_notes": [...],
-  "project_activity": {
-    "research-project": {
-      "operations": 5,
-      "last_used": "30 minutes ago",
-      "recent_folders": ["experiments", "findings"]
-    },
-    "work-notes": {
-      "operations": 2,
-      "last_used": "2 hours ago",
-      "recent_folders": ["meetings", "planning"]
-    }
-  },
-  "total_projects": 3
-}
-```
-
-#### Response Format Updates
-```
-✓ Note created successfully
-
-Project: research-project
-File: experiments/Neural Network Results.md
-Permalink: research-project/neural-network-results
-```
-
-### Phase 2: Cloud Service Simplification (basic-memory-cloud repository)
-
-#### Remove Session Infrastructure
-1. Delete `apps/mcp/src/basic_memory_cloud_mcp/middleware/session_state.py`
-2. Delete `apps/mcp/src/basic_memory_cloud_mcp/middleware/session_logging.py`
-3. Update `apps/mcp/src/basic_memory_cloud_mcp/main.py`:
-   ```python
-   # Remove session middleware
-   # server.add_middleware(SessionStateMiddleware)
-
-   # Enable stateless HTTP
-   mcp = FastMCP(name="basic-memory-mcp", stateless_http=True)
-   ```
-
-#### Deployment Simplification
-1. Remove Redis from `fly.toml`
-2. Remove Redis environment variables
-3. Update health checks to not depend on Redis
-
-### Phase 3: Conversational Project Management
-
-#### Claude Behavior Pattern
-1. **Project Discovery**:
-   ```
-   Claude: Let me check your recent activity...
-   [calls recent_activity() - no project needed for discovery]
-
-   I see you've been working in:
-   - research-project (5 operations, 30 min ago)
-   - work-notes (2 operations, 2 hours ago)
-
-   Which project should I use for this operation?
-   ```
-
-2. **Context Maintenance**:
-   ```
-   User: Use research-project
-   Claude: Working in research-project.
-   [All subsequent operations use project="research-project"]
-   ```
-
-3. **Explicit Project Switching**:
-   ```
-   User: Check work-notes for that meeting summary
-   Claude: Let me search work-notes for the meeting summary.
-   [Uses project="work-notes" for specific operation]
-   ```
-
-## How to Evaluate
-
-### Success Criteria
-
-#### 1. Functional Completeness
-- [x] All MCP tools accept required `project` parameter
-- [x] All MCP tools validate project exists before execution
-- [x] `switch_project` and `get_current_project` tools removed
-- [x] All responses display target project clearly
-- [ ] No Redis dependencies in deployment (Phase 2: Cloud Service)
-- [x] `recent_activity` shows project distribution with ProjectActivitySummary
-
-#### 2. Cross-Client Compatibility Testing
-Test identical operations across all clients:
-- [ ] **Claude Desktop**: All operations work with explicit projects
-- [ ] **Claude Code**: All operations work with explicit projects
-- [ ] **Claude Mobile iOS**: All operations work with explicit projects
-- [ ] **API clients**: All operations work with explicit projects
-- [ ] **CLI tools**: All operations work with explicit projects
-
-#### 3. Session Independence Verification
-- [ ] Operations work identically with/without session tracking
-- [ ] No behavioral differences between clients
-- [ ] Mobile client session ID changes do not affect operations
-- [ ] Redis can be completely removed without functional impact
-
-#### 4. Performance & Scaling
-- [ ] `stateless_http=True` enabled successfully
-- [ ] No Redis memory usage
-- [ ] Horizontal scaling possible (multiple MCP instances)
-- [ ] Response times unchanged or improved
-
-#### 5. User Experience Testing
-**Project Discovery Flow**:
-- [x] `recent_activity()` provides useful project context
-- [x] Claude can intelligently suggest projects based on activity
-- [x] Project switching is explicit and clear in conversation
-
-**Error Handling**:
-- [x] Clear error messages for non-existent projects
-- [x] Helpful suggestions when project parameter missing
-- [x] No silent failures or wrong-project operations
-
-**Response Clarity**:
-- [x] Every operation clearly shows target project
-- [x] Users always know which project is being operated on
-- [x] No confusion about "current project" state
-
-#### 6. Migration Safety
-- [ ] Backward compatibility period with optional project parameter
-- [ ] Clear migration documentation for existing users
-- [ ] Data integrity maintained during transition
-- [ ] No data loss during migration
-
-### Test Scenarios
-
-#### Core Functionality Test
-```bash
-# Test all tools work with explicit project
-write_note(project="test-proj", title="Test", content="Content", folder="docs")
-read_note(project="test-proj", identifier="Test")
-edit_note(project="test-proj", identifier="Test", operation="append", content="More")
-search_notes(project="test-proj", query="Content")
-list_directory(project="test-proj", dir_name="docs")
-delete_note(project="test-proj", identifier="Test")
-```
-
-#### Cross-Client Consistency Test
-Run identical test sequence on:
-1. Claude Desktop
-2. Claude Code
-3. Claude Mobile iOS
-4. API client
-5. CLI tools
-
-Verify all clients:
-- Accept explicit project parameters
-- Return identical responses
-- Show same project information
-- Have no session dependencies
-
-#### Session Independence Test
-1. Monitor session IDs during operations
-2. Verify operations work with changing session IDs
-3. Confirm Redis removal doesn't affect functionality
-4. Test with multiple concurrent clients
-
-### Acceptance Criteria
-
-**Must Have**:
-- All MCP tools require and use explicit project parameter
-- No session state dependencies remain
-- Universal client compatibility achieved
-- Clear project information in all responses
-
-**Should Have**:
-- Enhanced `recent_activity` with project distribution
-- Smooth migration path for existing users
-- Improved performance with stateless architecture
-
-**Could Have**:
-- Smart project suggestions based on content/context
-- Project shortcuts for common operations
-- Advanced project analytics in responses
-
-## Notes
-
-### Breaking Changes
-This is a **breaking change** that requires:
-- All MCP clients to pass project parameter
-- Migration of existing workflows
-- Update of all documentation and examples
-
-### Implementation Order
-1. **basic-memory core** - Update MCP tools to accept project parameter (optional initially)
-2. **Testing** - Verify all clients work with explicit projects
-3. **Cloud service** - Remove session infrastructure
-4. **Migration** - Make project parameter mandatory
-5. **Cleanup** - Remove deprecated tools and middleware
-
-### Related Issues
-- Fixes #74 (Claude iOS session state bug)
-- Implements #75 (Mandatory project parameter architecture)
-- Enables future horizontal scaling
-- Simplifies multi-tenant architecture
-
-### Dependencies
-- Requires coordination between basic-memory and basic-memory-cloud repositories
-- Needs client-side updates for smooth transition
-- Documentation updates across all materials

specs/SPEC-7 POC to spike Tigris Turso for local access to cloud data.md

@@ -1,193 +0,0 @@
----
-title: 'SPEC-7: POC to spike Tigris/Turso for local access to cloud data'
-type: spec
-permalink: specs/spec-7-poc-tigris-turso-local-access-cloud-data
-tags:
-- poc
-- tigris
-- turso
-- cloud-storage
-- architecture
-- proof-of-concept
----
-
-# SPEC-7: POC to spike Tigris/Turso for local access to cloud data
-
-## Why
-
-Current basic-memory-cloud architecture uses Fly volumes for tenant file storage, which creates several limitations:
-
-1. **Storage Scalability**: Fly volumes require pre-provisioning and don't auto-scale with usage
-2. **Cost Model**: Volume pricing vs object storage pricing may be less favorable at scale
-3. **Local Development**: No way for users to mount their cloud tenant files locally for real-time editing
-4. **Multi-Region**: Volumes are region-locked, limiting global deployment flexibility
-5. **Backup/Disaster Recovery**: Object storage provides better durability and replication options
-
-The core insight is that Basic Memory requires POSIX filesystem semantics but could benefit from object storage durability and accessibility. By combining:
-- **Tigris object storage** for file persistence (via rclone mount)
-- **Turso/libSQL** for SQLite indexing (replacing local .db files)
-
-We could enable a revolutionary user experience: **local editing of cloud-stored files** while maintaining Basic Memory's existing filesystem assumptions.
-
-## What
-
-This specification defines a proof-of-concept to validate the technical feasibility of the Tigris/Turso architecture for basic-memory-cloud tenants.
-
-**Affected Areas:**
-- **Storage Architecture**: Replace Fly volumes with Tigris object storage
-- **Database Architecture**: Replace local SQLite with Turso remote database
-- **Container Setup**: Add rclone mounting in tenant containers
-- **Local Development**: Enable local mounting of cloud tenant data
-- **Basic Memory Core**: Validate unchanged operation over mounted filesystems
-
-**Key Components:**
-- **Tigris Storage**: S3-compatible object storage via Fly.io integration
-- **rclone NFS Mount**: Native NFS mounting without FUSE dependencies
-- **Turso Database**: Hosted libSQL for SQLite replacement
-- **Single-Tenant Model**: One bucket + one database per tenant (simplified isolation)
-
-## How (High Level)
-
-### Phase 1: Local POC Validation
-- [ ] Set up Tigris bucket with test data
-- [ ] Configure rclone NFS mount locally
-- [ ] Test Basic Memory operations over mounted filesystem
-- [ ] Measure performance characteristics and identify issues
-- [ ] Validate file watching, sync operations, and concurrent access patterns
-
-### Phase 2: Database Migration
-- [ ] Set up Turso account and test database
-- [ ] Modify Basic Memory to accept external DATABASE_URL
-- [ ] Test all operations with remote SQLite via Turso
-- [ ] Validate performance and functionality parity
-
-### Phase 3: Container Integration
-- [ ] Create container image with rclone + NFS support
-- [ ] Implement tenant-specific credential management
-- [ ] Test container startup with automatic mounting
-- [ ] Validate isolation between tenant containers
-
-### Phase 4: Local Access Validation
-- [ ] Test local rclone mounting of tenant data
-- [ ] Validate real-time file editing experience
-- [ ] Test conflict resolution and sync behavior
-- [ ] Measure latency impact on user experience
-
-### Architecture Overview
-```
-Local Development:
-┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
-│ Local rclone    │───▶│ Tigris Bucket   │◀───│ Tenant Container│
-│ NFS Mount       │    │ (S3 storage)    │    │ rclone mount    │
-└─────────────────┘    └─────────────────┘    └─────────────────┘
-         │                                              │
-         ▼                                              ▼
-┌─────────────────┐                            ┌─────────────────┐
-│ Basic Memory    │                            │ Basic Memory    │
-│ (local files)   │                            │ (mounted files) │
-└─────────────────┘                            └─────────────────┘
-         │                                              │
-         ▼                                              ▼
-┌─────────────────┐                            ┌─────────────────┐
-│ Turso Database  │◀───────────────────────────│ Turso Database  │
-│ (shared index)  │                            │ (shared index)  │
-└─────────────────┘                            └─────────────────┘
-```
-
-## How to Evaluate
-
-### Success Criteria
-- [ ] **Filesystem Compatibility**: Basic Memory operates without modification over rclone-mounted Tigris storage
-- [ ] **Performance Acceptable**: File operations complete within 2x local filesystem latency
-- [ ] **Database Functionality**: All Basic Memory features work with Turso remote SQLite
-- [ ] **Container Reliability**: Tenant containers start successfully with automatic mounting
-- [ ] **Local Access**: Users can mount and edit cloud files locally with real-time sync
-- [ ] **Data Isolation**: Tenant data remains properly isolated using bucket/database separation
-
-### Testing Procedure
-1. **Local Filesystem Test**:
-   ```bash
-   # Mount Tigris bucket locally
-   rclone nfsmount tigris:test-bucket ~/tigris-test --vfs-cache-mode writes
-
-   # Run Basic Memory operations
-   cd ~/tigris-test && basic-memory sync --watch
-   # Test: create notes, search, file watching, bulk operations
-   ```
-
-2. **Database Migration Test**:
-   ```bash
-   # Configure Turso connection
-   export DATABASE_URL="libsql://test-db.turso.io?authToken=..."
-
-   # Test all MCP tools with remote database
-   basic-memory tools # Test each tool functionality
-   ```
-
-3. **Container Integration Test**:
-   ```dockerfile
-   # Test container with rclone mounting
-   FROM python:3.12
-   RUN apt-get update && apt-get install -y rclone nfs-common
-   # ... test startup and mounting process
-   ```
-
-4. **Performance Benchmarking**:
-   - File creation/read/write operations (target: <2x local latency)
-   - Search query performance (target: comparable to local SQLite)
-   - File watching responsiveness (target: events within 1-2 seconds)
-   - Concurrent operation handling
-
-### Risk Assessment
-**High Risk Items**:
-- [ ] NFS-over-S3 performance may be insufficient for real-time operations
-- [ ] File watching (`inotify`) over NFS may be unreliable
-- [ ] Network interruptions could cause filesystem errors
-- [ ] Concurrent access patterns might hit S3 rate limits
-
-**Mitigation Strategies**:
-- Comprehensive performance testing before committing to architecture
-- Fallback plan to S3-native storage backend if filesystem approach fails
-- Extensive error handling and retry logic for network issues
-
-### Metrics to Track
-- **Latency**: File operation response times (read/write/watch)
-- **Reliability**: Success rate of file operations over time
-- **Throughput**: Concurrent file operations and search queries
-- **User Experience**: Perceived performance for local mounting use case
-
-## Notes
-
-### Key Architectural Decisions
-- **Single tenant per bucket/database**: Simplifies isolation and credential management
-- **Maintain POSIX compatibility**: Preserve Basic Memory's existing filesystem assumptions
-- **NFS over FUSE**: Better compatibility and performance characteristics
-- **Turso for SQLite**: Leverages specialized remote SQLite expertise
-
-### Alternative Approaches Considered
-- **S3-native storage backend**: Would require Basic Memory architecture changes
-- **Hybrid approach**: Local files + cloud sync (adds complexity)
-- **FUSE mounting**: More platform dependencies and kernel requirements
-
-### Integration Points
-- [ ] Fly.io Tigris integration for bucket provisioning
-- [ ] Turso account setup and database provisioning
-- [ ] Container image modifications for rclone support
-- [ ] Credential management for tenant isolation
-
-## Observations
-
-- [architecture] Tigris/Turso split cleanly separates file storage from indexing concerns #storage-separation
-- [user-experience] Local mounting of cloud files could be revolutionary for knowledge management #local-cloud-hybrid
-- [compatibility] Maintaining POSIX filesystem assumptions preserves Basic Memory's local/cloud compatibility #architecture-preservation
-- [simplification] Single tenant per bucket eliminates complex multi-tenancy in storage layer #tenant-isolation
-- [risk] NFS-over-S3 performance characteristics are unproven for real-time operations #performance-risk
-- [benefit] Object storage pricing model could be more favorable than volume pricing #cost-optimization
-- [innovation] Real-time local editing of cloud-stored files addresses major SaaS limitation #competitive-advantage
-
-## Relations
-
-- implements [[SPEC-6 Explicit Project Parameter Architecture]]
-- requires [[Fly.io Tigris Integration]]
-- enables [[Local Cloud File Access]]
-- alternative_to [[Fly Volume Storage]]

specs/SPEC-8 TigrisFS Integration.md

@@ -1,886 +0,0 @@
----
-title: 'SPEC-8: TigrisFS Integration for Tenant API'
-Date: September 22, 2025
-Status: Phase 3.6 Complete - Tenant Mount API Endpoints Ready for CLI Implementation
-Priority: High
-Goal: Replace Fly volumes with Tigris bucket provisioning in production tenant API
-permalink: spec-8-tigris-fs-integration
----
-
-## Executive Summary
-
-Based on SPEC-7 Phase 4 POC testing, this spec outlines productizing the TigrisFS/rclone implementation in the Basic Memory Cloud tenant API. 
-We're moving from proof-of-concept to production integration, replacing Fly volume storage with Tigris bucket-per-tenant architecture.
-
-## Current Architecture (Fly Volumes)
-
-### Tenant Provisioning Flow
-```python
-# apps/cloud/src/basic_memory_cloud/workflows/tenant_provisioning.py
-async def provision_tenant_infrastructure(tenant_id: str):
-    # 1. Create Fly app
-    # 2. Create Fly volume  ← REPLACE THIS
-    # 3. Deploy API container with volume mount
-    # 4. Configure health checks
-```
-
-### Storage Implementation
-- Each tenant gets dedicated Fly volume (1GB-10GB)
-- Volume mounted at `/app/data` in API container
-- Local filesystem storage with Basic Memory indexing
-- No global caching or edge distribution
-
-## Proposed Architecture (Tigris Buckets)
-
-### New Tenant Provisioning Flow
-```python
-async def provision_tenant_infrastructure(tenant_id: str):
-    # 1. Create Fly app
-    # 2. Create Tigris bucket with admin credentials  ← NEW
-    # 3. Store bucket name in tenant record  ← NEW
-    # 4. Deploy API container with TigrisFS mount using admin credentials
-    # 5. Configure health checks
-```
-
-### Storage Implementation
-- Each tenant gets dedicated Tigris bucket
-- TigrisFS mounts bucket at `/app/data` in API container
-- Global edge caching and distribution
-- Configurable cache TTL for sync performance
-
-## Implementation Plan
-
-### Phase 1: Bucket Provisioning Service
-
-**✅ IMPLEMENTED: StorageClient with Admin Credentials**
-```python
-# apps/cloud/src/basic_memory_cloud/clients/storage_client.py
-class StorageClient:
-    async def create_tenant_bucket(self, tenant_id: UUID) -> TigrisBucketCredentials
-    async def delete_tenant_bucket(self, tenant_id: UUID, bucket_name: str) -> bool
-    async def list_buckets(self) -> list[TigrisBucketResponse]
-    async def test_tenant_credentials(self, credentials: TigrisBucketCredentials) -> bool
-```
-
-**Simplified Architecture Using Admin Credentials:**
-- Single admin access key with full Tigris permissions (configured in console)
-- No tenant-specific IAM user creation needed
-- Bucket-per-tenant isolation for logical separation
-- Admin credentials shared across all tenant operations
-
-**Integrate with Provisioning workflow:**
-```python
-# Update tenant_provisioning.py
-async def provision_tenant_infrastructure(tenant_id: str):
-    storage_client = StorageClient(settings.aws_access_key_id, settings.aws_secret_access_key)
-    bucket_creds = await storage_client.create_tenant_bucket(tenant_id)
-    await store_bucket_name(tenant_id, bucket_creds.bucket_name)
-    await deploy_api_with_tigris(tenant_id, bucket_creds)
-```
-
-### Phase 2: Simplified Bucket Management
-
-**✅ SIMPLIFIED: Admin Credentials + Bucket Names Only**
-
-Since we use admin credentials for all operations, we only need to track bucket names per tenant:
-
-1. **Primary Storage (Fly Secrets)**
-   ```bash
-   flyctl secrets set -a basic-memory-{tenant_id} \
-     AWS_ACCESS_KEY_ID="{admin_access_key}" \
-     AWS_SECRET_ACCESS_KEY="{admin_secret_key}" \
-     AWS_ENDPOINT_URL_S3="https://fly.storage.tigris.dev" \
-     AWS_REGION="auto" \
-     BUCKET_NAME="basic-memory-{tenant_id}"
-   ```
-
-2. **Database Storage (Bucket Name Only)**
-   ```python
-   # apps/cloud/src/basic_memory_cloud/models/tenant.py
-   class Tenant(BaseModel):
-       # ... existing fields
-       tigris_bucket_name: Optional[str] = None  # Just store bucket name
-       tigris_region: str = "auto"
-       created_at: datetime
-   ```
-
-**Benefits of Simplified Approach:**
-- No credential encryption/decryption needed
-- Admin credentials managed centrally in environment
-- Only bucket names stored in database (not sensitive)
-- Simplified backup/restore scenarios
-- Reduced security attack surface
-
-### Phase 3: API Container Updates
-
-**Update API container configuration:**
-```dockerfile
-# apps/api/Dockerfile
-# Add TigrisFS installation
-RUN curl -L https://github.com/tigrisdata/tigrisfs/releases/latest/download/tigrisfs-linux-amd64 \
-    -o /usr/local/bin/tigrisfs && chmod +x /usr/local/bin/tigrisfs
-```
-
-**Startup script integration:**
-```bash
-# apps/api/tigrisfs-startup.sh (already exists)
-# Mount TigrisFS → Start Basic Memory API
-exec python -m basic_memory_cloud_api.main
-```
-
-**Fly.toml environment (optimized for < 5s startup):**
-```toml
-# apps/api/fly.tigris-production.toml
-[env]
-  TIGRISFS_MEMORY_LIMIT = '1024'     # Reduced for faster init
-  TIGRISFS_MAX_FLUSHERS = '16'       # Fewer threads for faster startup
-  TIGRISFS_STAT_CACHE_TTL = '30s'    # Balance sync speed vs startup
-  TIGRISFS_LAZY_INIT = 'true'        # Enable lazy loading
-  BASIC_MEMORY_HOME = '/app/data'
-
-# Suspend optimization for wake-on-network
-[machine]
-  auto_stop_machines = "suspend"     # Faster than full stop
-  auto_start_machines = true
-  min_machines_running = 0
-```
-
-### Phase 4: Local Access Features
-
-**CLI automation for local mounting:**
-```python
-# New CLI command: basic-memory cloud mount
-async def setup_local_mount(tenant_id: str):
-    # 1. Fetch bucket credentials from cloud API
-    # 2. Configure rclone with scoped IAM policy
-    # 3. Mount via rclone nfsmount (macOS) or FUSE (Linux)
-    # 4. Start Basic Memory sync watcher
-```
-
-**Local mount configuration:**
-```bash
-# rclone config for tenant
-rclone mount basic-memory-{tenant_id}: ~/basic-memory-{tenant_id} \
-  --nfs-mount \
-  --vfs-cache-mode writes \
-  --cache-dir ~/.cache/rclone/basic-memory-{tenant_id}
-```
-
-### Phase 5: TigrisFS Cache Sync Solutions
-
-**Problem**: When files are uploaded via CLI/bisync, the tenant API container doesn't see them immediately due to TigrisFS cache (30s TTL) and lack of inotify events on mounted filesystems.
-
-**Multi-Layer Solution:**
-
-**Layer 1: API Sync Endpoint** (Immediate)
-```python
-# POST /sync - Force TigrisFS cache refresh
-# Callable by CLI after uploads
-subprocess.run(["sync", "fsync /app/data"], check=True)
-```
-
-**Layer 2: Tigris Webhook Integration** (Real-time)
-https://www.tigrisdata.com/docs/buckets/object-notifications/#webhook
-```python
-# Webhook endpoint for bucket changes
-@app.post("/webhooks/tigris/{tenant_id}")
-async def handle_bucket_notification(tenant_id: str, event: TigrisEvent):
-    if event.eventName in ["OBJECT_CREATED_PUT", "OBJECT_DELETED"]:
-        await notify_container_sync(tenant_id, event.object.key)
-```
-
-**Layer 3: CLI Sync Notification** (User-triggered)
-```bash
-# CLI calls container sync endpoint after successful bisync
-basic-memory cloud bisync  # Automatically notifies container
-curl -X POST https://basic-memory-{tenant-id}.fly.dev/sync
-```
-
-**Layer 4: Periodic Sync Fallback** (Safety net)
-```python
-# Background task: fsync /app/data every 30s as fallback
-# Ensures eventual consistency even if other layers fail
-```
-
-**Implementation Priority:**
-1. Layer 1 (API endpoint) - Quick testing capability
-2. Layer 3 (CLI integration) - Improved UX
-3. Layer 4 (Periodic fallback) - Safety net
-4. Layer 2 (Webhooks) - Production real-time sync
-
-
-## Performance Targets
-
-### Sync Latency
-- **Target**: < 5 seconds local→cloud→container
-- **Configuration**: `TIGRISFS_STAT_CACHE_TTL = '5s'`
-- **Monitoring**: Track sync metrics in production
-
-### Container Startup
-- **Target**: < 5 seconds including TigrisFS mount
-- **Fast retry**: 0.5s intervals for mount verification
-- **Fallback**: Container fails fast if mount fails
-
-### Memory Usage
-- **TigrisFS cache**: 2GB memory limit per container
-- **Concurrent uploads**: 32 flushers max
-- **VM sizing**: shared-cpu-2x (2048mb) minimum
-
-## Security Considerations
-
-### Bucket Isolation
-- Each tenant has dedicated bucket
-- IAM policies prevent cross-tenant access
-- No shared bucket with subdirectories
-
-### Credential Security
-- Fly secrets for runtime access
-- Encrypted database backup for disaster recovery
-- Credential rotation capability
-
-### Data Residency
-- Tigris global edge caching
-- SOC2 Type II compliance
-- Encryption at rest and in transit
-
-## Operational Benefits
-
-### Scalability
-- Horizontal scaling with stateless API containers
-- Global edge distribution
-- Better resource utilization
-
-### Reliability
-- No cold starts between tenants
-- Built-in redundancy and caching
-- Simplified backup strategy
-
-### Cost Efficiency
-- Pay-per-use storage pricing
-- Shared infrastructure benefits
-- Reduced operational overhead
-
-## Risk Mitigation
-
-### Data Loss Prevention
-- Dual credential storage (Fly + database)
-- Automated backup workflows to R2/S3
-- Tigris built-in redundancy
-
-### Performance Degradation
-- Configurable cache settings per tenant
-- Monitoring and alerting on sync latency
-- Fallback to volume storage if needed
-
-### Security Vulnerabilities
-- Bucket-per-tenant isolation
-- Regular credential rotation
-- Security scanning and monitoring
-
-## Success Metrics
-
-### Technical Metrics
-- Sync latency P50 < 5 seconds
-- Container startup time < 5 seconds
-- Zero data loss incidents
-- 99.9% uptime per tenant
-
-### Business Metrics
-- Reduced infrastructure costs vs volumes
-- Improved user experience with faster sync
-- Enhanced enterprise security posture
-- Simplified operational overhead
-
-## Open Questions
-
-1. **Tigris rate limits**: What are the API limits for bucket creation?
-2. **Cost analysis**: What's the break-even point vs Fly volumes?
-3. **Regional preferences**: Should enterprise customers choose regions?
-4. **Backup retention**: How long to keep automated backups?
-
-## Implementation Checklist
-
-### Phase 1: Bucket Provisioning Service ✅ COMPLETED
-- [x] **Research Tigris bucket API** - Document bucket creation and S3 API compatibility
-- [x] **Create StorageClient class** - Implemented with admin credentials and comprehensive integration tests
-- [x] **Test bucket creation** - Full test suite validates API integration with real Tigris environment
-- [x] **Add bucket provisioning to DBOS workflow** - Integrated StorageClient with tenant_provisioning.py
-
-### Phase 2: Simplified Bucket Management ✅ COMPLETED
-- [x] **Update Tenant model** with tigris_bucket_name field (replaced fly_volume_id)
-- [x] **Implement bucket name storage** - Database migration and model updates completed
-- [x] **Test bucket provisioning integration** - Full test suite validates workflow from tenant creation to bucket assignment
-- [x] **Remove volume logic from all tests** - Complete migration from volume-based to bucket-based architecture
-
-### Phase 3: API Container Integration ✅ COMPLETED
-- [x] **Update Dockerfile** to install TigrisFS binary in API container with configurable version
-- [x] **Optimize tigrisfs-startup.sh** with production-ready security and reliability improvements
-- [x] **Create production-ready container** with proper signal handling and mount validation
-- [x] **Implement security fixes** based on Claude code review (conditional debug, credential protection)
-- [x] **Add proper process supervision** with cleanup traps and error handling
-- [x] **Remove debug artifacts** - Cleaned up all debug Dockerfiles and test scripts
-
-### Phase 3.5: IAM Access Key Management ✅ COMPLETED
-- [x] **Research Tigris IAM API** - Documented create_policy, attach_user_policy, delete_access_key operations
-- [x] **Implement bucket-scoped credential generation** - StorageClient.create_tenant_access_keys() with IAM policies
-- [x] **Add comprehensive security test suite** - 5 security-focused integration tests covering all attack vectors
-- [x] **Verify cross-bucket access prevention** - Scoped credentials can ONLY access their designated bucket
-- [x] **Test credential lifecycle management** - Create, validate, delete, and revoke access keys
-- [x] **Validate admin vs scoped credential isolation** - Different access patterns and security boundaries
-- [x] **Test multi-tenant isolation** - Multiple tenants cannot access each other's buckets
-
-### Phase 3.6: Tenant Mount API Endpoints ✅ COMPLETED
-- [x] **Implement GET /tenant/mount/info** - Returns mount info without exposing credentials
-- [x] **Implement POST /tenant/mount/credentials** - Creates new bucket-scoped credentials for CLI mounting
-- [x] **Implement DELETE /tenant/mount/credentials/{cred_id}** - Revoke specific credentials with proper cleanup
-- [x] **Implement GET /tenant/mount/credentials** - List active credentials without exposing secrets
-- [x] **Add TenantMountCredentials database model** - Tracks credential metadata (no secret storage)
-- [x] **Create comprehensive test suite** - 28 tests covering all scenarios including multi-session support
-- [x] **Implement multi-session credential flow** - Multiple active credentials per tenant supported
-- [x] **Secure credential handling** - Secret keys never stored, returned once only for immediate use
-- [x] **Add dependency injection for StorageClient** - Clean integration with existing API architecture
-- [x] **Fix Tigris configuration for cloud service** - Added AWS environment variables to fly.template.toml
-- [x] **Update tenant machine configurations** - Include AWS credentials for TigrisFS mounting with clear credential strategy
-
-**Security Test Results:**
-```
-✅ Cross-bucket access prevention - PASS
-✅ Deleted credentials access revoked - PASS
-✅ Invalid credentials rejected - PASS
-✅ Admin vs scoped credential isolation - PASS
-✅ Multiple scoped credentials isolation - PASS
-```
-
-**Implementation Details:**
-- Uses Tigris IAM managed policies (create_policy + attach_user_policy)
-- Bucket-scoped S3 policies with Actions: GetObject, PutObject, DeleteObject, ListBucket
-- Resource ARNs limited to specific bucket: `arn:aws:s3:::bucket-name` and `arn:aws:s3:::bucket-name/*`
-- Access keys follow Tigris format: `tid_` prefix with secure random suffix
-- Complete cleanup on deletion removes both access keys and associated policies
-
-### Phase 4: Local Access CLI
-- [x] **Design local mount CLI command** for automated rclone configuration
-- [x] **Implement credential fetching** from cloud API for local setup
-- [x] **Create rclone config automation** for tenant-specific bucket mounting
-- [x] **Test local→cloud→container sync** with optimized cache settings
-- [x] **Document local access setup** for beta users
-
-### Phase 5: Webhook Integration (Future)
-- [ ] **Research Tigris webhook API** for object notifications and payload format
-- [ ] **Design webhook endpoint** for real-time sync notifications
-- [ ] **Implement notification handling** to trigger Basic Memory sync events
-- [ ] **Test webhook delivery** and sync latency improvements
-
-## Success Metrics
-- [ ] **Container startup < 5 seconds** including TigrisFS mount and Basic Memory init
-- [ ] **Sync latency < 5 seconds** for local→cloud→container file changes
-- [ ] **Zero data loss** during bucket provisioning and credential management
-- [ ] **100% test coverage** for new TigrisBucketService and credential functions
-- [ ] **Beta deployment** with internal users validating local-cloud workflow
-
-
-
-## Implementation Notes
-
-## Phase 4.1: Bidirectional Sync with rclone bisync (NEW)
-
-### Problem Statement
-During testing, we discovered that some applications (particularly Obsidian) don't detect file changes over NFS mounts. Rather than building a custom sync daemon, we can leverage `rclone bisync` - rclone's built-in bidirectional synchronization feature.
-
-### Solution: rclone bisync
-Use rclone's proven bidirectional sync instead of custom implementation:
-
-**Core Architecture:**
-```bash
-# rclone bisync handles all the complexity
-rclone bisync ~/basic-memory-{tenant_id} basic-memory-{tenant_id}:{bucket_name} \
-  --create-empty-src-dirs \
-  --conflict-resolve newer \
-  --resilient \
-  --check-access
-```
-
-**Key Benefits:**
-- ✅ **Battle-tested**: Production-proven rclone functionality
-- ✅ **MIT licensed**: Open source with permissive licensing
-- ✅ **No custom code**: Zero maintenance burden for sync logic
-- ✅ **Built-in safety**: max-delete protection, conflict resolution
-- ✅ **Simple installation**: Works with Homebrew rclone (no FUSE needed)
-- ✅ **File watcher compatible**: Works with Obsidian and all applications
-- ✅ **Offline support**: Can work offline and sync when connected
-
-### bisync Conflict Resolution Options
-
-**Built-in conflict strategies:**
-```bash
---conflict-resolve none     # Keep both files with .conflict suffixes (safest)
---conflict-resolve newer    # Always pick the most recently modified file
---conflict-resolve larger   # Choose based on file size
---conflict-resolve path1    # Always prefer local changes
---conflict-resolve path2    # Always prefer cloud changes
-```
-
-### Sync Profiles Using bisync
-
-**Profile configurations:**
-```python
-BISYNC_PROFILES = {
-    "safe": {
-        "conflict_resolve": "none",      # Keep both versions
-        "max_delete": 10,                # Prevent mass deletion
-        "check_access": True,            # Verify sync integrity
-        "description": "Safe mode with conflict preservation"
-    },
-    "balanced": {
-        "conflict_resolve": "newer",     # Auto-resolve to newer file
-        "max_delete": 25,
-        "check_access": True,
-        "description": "Balanced mode (recommended default)"
-    },
-    "fast": {
-        "conflict_resolve": "newer",
-        "max_delete": 50,
-        "check_access": False,           # Skip verification for speed
-        "description": "Fast mode for rapid iteration"
-    }
-}
-```
-
-### CLI Commands
-
-**Manual sync commands:**
-```bash
-basic-memory cloud bisync                    # Manual bidirectional sync
-basic-memory cloud bisync --dry-run          # Preview changes
-basic-memory cloud bisync --profile safe     # Use specific profile
-basic-memory cloud bisync --resync           # Force full baseline resync
-```
-
-**Watch mode (Step 1):**
-```bash
-basic-memory cloud bisync --watch            # Long-running process, sync every 60s
-basic-memory cloud bisync --watch --interval 30s  # Custom interval
-```
-
-**System integration (Step 2 - Future):**
-```bash
-basic-memory cloud bisync-service install    # Install as system service
-basic-memory cloud bisync-service start      # Start background service
-basic-memory cloud bisync-service status     # Check service status
-```
-
-### Implementation Strategy
-
-**Phase 4.1.1: Core bisync Implementation**
-- [ ] Implement `run_bisync()` function wrapping rclone bisync
-- [ ] Add profile-based configuration (safe/balanced/fast)
-- [ ] Create conflict resolution and safety options
-- [ ] Test with sample files and conflict scenarios
-
-**Phase 4.1.2: Watch Mode**
-- [ ] Add `--watch` flag for continuous sync
-- [ ] Implement configurable sync intervals
-- [ ] Add graceful shutdown and signal handling
-- [ ] Create status monitoring and progress indicators
-
-**Phase 4.1.3: User Experience**
-- [ ] Add conflict reporting and resolution guidance
-- [ ] Implement dry-run preview functionality
-- [ ] Create troubleshooting and diagnostic commands
-- [ ] Add filtering configuration (.gitignore-style)
-
-**Phase 4.1.4: System Integration (Future)**
-- [ ] Generate platform-specific service files (launchd/systemd)
-- [ ] Add service management commands
-- [ ] Implement automatic startup and recovery
-- [ ] Create monitoring and logging integration
-
-### Technical Implementation
-
-**Core bisync wrapper:**
-```python
-def run_bisync(
-    tenant_id: str,
-    bucket_name: str,
-    profile: str = "balanced",
-    dry_run: bool = False
-) -> bool:
-    """Run rclone bisync with specified profile."""
-
-    local_path = Path.home() / f"basic-memory-{tenant_id}"
-    remote_path = f"basic-memory-{tenant_id}:{bucket_name}"
-    profile_config = BISYNC_PROFILES[profile]
-
-    cmd = [
-        "rclone", "bisync",
-        str(local_path), remote_path,
-        "--create-empty-src-dirs",
-        "--resilient",
-        f"--conflict-resolve={profile_config['conflict_resolve']}",
-        f"--max-delete={profile_config['max_delete']}",
-        "--filters-file", "~/.basic-memory/bisync-filters.txt"
-    ]
-
-    if profile_config.get("check_access"):
-        cmd.append("--check-access")
-
-    if dry_run:
-        cmd.append("--dry-run")
-
-    return subprocess.run(cmd, check=True).returncode == 0
-```
-
-**Default filter file (~/.basic-memory/bisync-filters.txt):**
-```
-- .DS_Store
-- .git/**
-- __pycache__/**
-- *.pyc
-- .pytest_cache/**
-- node_modules/**
-- .conflict-*
-- Thumbs.db
-- desktop.ini
-```
-
-**Advantages Over Custom Daemon:**
-- ✅ **Zero maintenance**: No custom sync logic to debug/maintain
-- ✅ **Production proven**: Used by thousands in production
-- ✅ **Safety features**: Built-in max-delete, conflict handling, recovery
-- ✅ **Filtering**: Advanced exclude patterns and rules
-- ✅ **Performance**: Optimized for various storage backends
-- ✅ **Community support**: Extensive documentation and community
-
-## Phase 4.2: NFS Mount Support (Direct Access)
-
-### Solution: rclone nfsmount
-Keep the existing NFS mount functionality for users who prefer direct file access:
-
-**Core Architecture:**
-```bash
-# rclone nfsmount provides transparent file access
-rclone nfsmount basic-memory-{tenant_id}:{bucket_name} ~/basic-memory-{tenant_id} \
-  --vfs-cache-mode writes \
-  --dir-cache-time 10s \
-  --daemon
-```
-
-**Key Benefits:**
-- ✅ **Real-time access**: Files appear immediately as they're created/modified
-- ✅ **Transparent**: Works with any application that reads/writes files
-- ✅ **Low latency**: Direct access without sync delays
-- ✅ **Simple**: No periodic sync commands needed
-- ✅ **Homebrew compatible**: Works with Homebrew rclone (no FUSE required)
-
-**Limitations:**
-- ❌ **File watcher compatibility**: Some apps (Obsidian) don't detect changes over NFS
-- ❌ **Network dependency**: Requires active connection to cloud storage
-- ❌ **Potential conflicts**: Simultaneous edits from multiple locations can cause issues
-
-### Mount Profiles (Existing)
-
-**Already implemented profiles from SPEC-7 testing:**
-```python
-MOUNT_PROFILES = {
-    "fast": {
-        "cache_time": "5s",
-        "poll_interval": "3s",
-        "description": "Ultra-fast development (5s sync)"
-    },
-    "balanced": {
-        "cache_time": "10s",
-        "poll_interval": "5s",
-        "description": "Fast development (10-15s sync, recommended)"
-    },
-    "safe": {
-        "cache_time": "15s",
-        "poll_interval": "10s",
-        "description": "Conflict-aware mount with backup",
-        "extra_args": ["--conflict-suffix", ".conflict-{DateTimeExt}"]
-    }
-}
-```
-
-### CLI Commands (Existing)
-
-**Mount commands already implemented:**
-```bash
-basic-memory cloud mount                     # Mount with balanced profile
-basic-memory cloud mount --profile fast     # Ultra-fast caching
-basic-memory cloud mount --profile safe     # Conflict detection
-basic-memory cloud unmount                  # Clean unmount
-basic-memory cloud mount-status             # Show mount status
-```
-
-## User Choice: Mount vs Bisync
-
-### When to Use Each Approach
-
-| Use Case | Recommended Solution | Why |
-|----------|---------------------|-----|
-| **Obsidian users** | `bisync` | File watcher support for live preview |
-| **CLI/vim/emacs users** | `mount` | Direct file access, lower latency |
-| **Offline work** | `bisync` | Can work offline, sync when connected |
-| **Real-time collaboration** | `mount` | Immediate visibility of changes |
-| **Multiple machines** | `bisync` | Better conflict handling |
-| **Single machine** | `mount` | Simpler, more transparent |
-| **Development work** | Either | Both work well, user preference |
-| **Large files** | `mount` | Streaming access vs full download |
-
-### Installation Simplicity
-
-**Both approaches now use simple Homebrew installation:**
-```bash
-# Single installation command for both approaches
-brew install rclone
-
-# No macFUSE, no system modifications needed
-# Works immediately with both mount and bisync
-```
-
-### Implementation Status
-
-**Phase 4.1: bisync** (NEW)
-- [ ] Implement bisync command wrapper
-- [ ] Add watch mode with configurable intervals
-- [ ] Create conflict resolution workflows
-- [ ] Add filtering and safety options
-
-**Phase 4.2: mount** (EXISTING - ✅ IMPLEMENTED)
-- [x] NFS mount commands with profile support
-- [x] Mount management and cleanup
-- [x] Process monitoring and health checks
-- [x] Credential integration with cloud API
-
-**Both approaches share:**
-- [x] Credential management via cloud API
-- [x] Secure rclone configuration
-- [x] Tenant isolation and bucket scoping
-- [x] Simple Homebrew rclone installation
-
-
-Key Features:
-
-1. Cross-Platform rclone Installation (rclone_installer.py):
-- macOS: Homebrew → official script fallback
-- Linux: snap → apt → official script fallback
-- Windows: winget → chocolatey → scoop fallback
-- Automatic version detection and verification
-
-2. Smart rclone Configuration (rclone_config.py):
-- Automatic tenant-specific config generation
-- Three optimized mount profiles from your SPEC-7 testing:
-- fast: 5s sync (ultra-performance)
-- balanced: 10-15s sync (recommended default)
-- safe: 15s sync + conflict detection
-- Backup existing configs before modification
-
-3. Robust Mount Management (mount_commands.py):
-- Automatic tenant credential generation
-- Mount path management (~/basic-memory-{tenant-id})
-- Process lifecycle management (prevent duplicate mounts)
-- Orphaned process cleanup
-- Mount verification and health checking
-
-4. Clean Architecture (api_client.py):
-- Separated API client to avoid circular imports
-- Reuses existing authentication infrastructure
-- Consistent error handling and logging
-
-User Experience:
-
-One-Command Setup:
-basic-memory cloud setup
-```bash 
-# 1. Installs rclone automatically
-# 2. Authenticates with existing login
-# 3. Generates secure credentials  
-# 4. Configures rclone
-# 5. Performs initial mount
-```
-
-Profile-Based Mounting:
-basic-memory cloud mount --profile fast      # 5s sync
-basic-memory cloud mount --profile balanced  # 15s sync (default)
-basic-memory cloud mount --profile safe      # conflict detection
-
-Status Monitoring:
-basic-memory cloud mount-status
-```bash 
-# Shows: tenant info, mount path, sync profile, rclone processes
-```
-### local mount api 
-
-Endpoint 1: Get Tenant Info for user
-Purpose: Get tenant details for mounting
-- pass in jwt
-- service returns mount info
-
-**✅ IMPLEMENTED API Specification:**
-
-**Endpoint 1: GET /tenant/mount/info**
-- Purpose: Get tenant mount information without exposing credentials
-- Authentication: JWT token (tenant_id extracted from claims)
-
-Request:
-```
-GET /tenant/mount/info
-Authorization: Bearer {jwt_token}
-```
-
-Response:
-```json
-{
-    "tenant_id": "434252dd-d83b-4b20-bf70-8a950ff875c4",
-    "bucket_name": "basic-memory-434252dd",
-    "has_credentials": true,
-    "credentials_created_at": "2025-09-22T16:48:50.414694"
-}
-```
-
-**Endpoint 2: POST /tenant/mount/credentials**
-- Purpose: Generate NEW bucket-scoped S3 credentials for rclone mounting
-- Authentication: JWT token (tenant_id extracted from claims)
-- Multi-session: Creates new credentials without revoking existing ones
-
-Request:
-```
-POST /tenant/mount/credentials
-Authorization: Bearer {jwt_token}
-Content-Type: application/json
-```
-*Note: No request body needed - tenant_id extracted from JWT*
-
-Response:
-```json
-{
-    "tenant_id": "434252dd-d83b-4b20-bf70-8a950ff875c4",
-    "bucket_name": "basic-memory-434252dd",
-    "access_key": "test_access_key_12345",
-    "secret_key": "test_secret_key_abcdef",
-    "endpoint_url": "https://fly.storage.tigris.dev",
-    "region": "auto"
-}
-```
-
-**🔒 Security Notes:**
-- Secret key returned ONCE only - never stored in database
-- Credentials are bucket-scoped (cannot access other tenants' buckets)
-- Multiple active credentials supported per tenant (work laptop + personal machine)
-
-Implementation Notes
-
-Security:
-- Both endpoints require JWT authentication
-- Extract tenant_id from JWT claims (not request body)
-- Generate scoped credentials (not admin credentials)
-- Credentials should have bucket-specific access only
-
-Integration Points:
-- Use your existing StorageClient from SPEC-8 implementation
-- Leverage existing JWT middleware for tenant extraction
-- Return same credential format as your Tigris bucket provisioning
-
-Error Handling:
-- 401 if not authenticated
-- 403 if tenant doesn't exist
-- 500 if credential generation fails
-
-**🔄 Design Decisions:**
-
-1. **Secure Credential Flow (No Secret Storage)**
-
-Based on CLI flow analysis, we follow security best practices:
-- ✅ API generates both access_key + secret_key via Tigris IAM
-- ✅ Returns both in API response for immediate use
-- ✅ CLI uses credentials immediately to configure rclone
-- ✅ Database stores only metadata (access_key + policy_arn for cleanup)
-- ✅ rclone handles secure local credential storage
-- ❌ **Never store secret_key in database (even encrypted)**
-
-2. **CLI Credential Flow**
-```bash
-# CLI calls API
-POST /tenant/mount/credentials → {access_key, secret_key, ...}
-
-# CLI immediately configures rclone
-rclone config create basic-memory-{tenant_id} s3 \
-  access_key_id={access_key} \
-  secret_access_key={secret_key} \
-  endpoint=https://fly.storage.tigris.dev
-
-# Database tracks metadata only
-INSERT INTO tenant_mount_credentials (tenant_id, access_key, policy_arn, ...)
-```
-
-3. **Multiple Sessions Supported**
-
-- Users can have multiple active credential sets (work laptop, personal machine, etc.)
-- Each credential generation creates a new Tigris access key
-- List active credentials via API (shows access_key but never secret)
-
-4. **Failure Handling & Cleanup**
-
-- **Happy Path**: Credentials created → Used immediately → rclone configured
-- **Orphaned Credentials**: Background job revokes unused credentials
-- **API Failure Recovery**: Retry Tigris deletion with stored policy_arn
-- **Status Tracking**: Track tigris_deletion_status (pending/completed/failed)
-
-5. **Event Sourcing & Audit**
-
-- MountCredentialCreatedEvent
-- MountCredentialRevokedEvent
-- MountCredentialOrphanedEvent (for cleanup)
-- Full audit trail for security compliance
-
-6. **Tenant/Bucket Validation**
-
-- Verify tenant exists and has valid bucket before credential generation
-- Use existing StorageClient to validate bucket access
-- Prevent credential generation for inactive/invalid tenants
-
-📋 **Implemented API Endpoints:**
-
-```
-✅ IMPLEMENTED:
-GET    /tenant/mount/info                    # Get tenant/bucket info (no credentials exposed)
-POST   /tenant/mount/credentials             # Generate new credentials (returns secret once)
-GET    /tenant/mount/credentials             # List active credentials (no secrets)
-DELETE /tenant/mount/credentials/{cred_id}   # Revoke specific credentials
-```
-
-**API Implementation Status:**
-- ✅ **GET /tenant/mount/info**: Returns tenant_id, bucket_name, has_credentials, credentials_created_at
-- ✅ **POST /tenant/mount/credentials**: Creates new bucket-scoped access keys, returns access_key + secret_key once
-- ✅ **GET /tenant/mount/credentials**: Lists active credentials without exposing secret keys
-- ✅ **DELETE /tenant/mount/credentials/{cred_id}**: Revokes specific credentials with proper Tigris IAM cleanup
-- ✅ **Multi-session support**: Multiple active credentials per tenant (work laptop + personal machine)
-- ✅ **Security**: Secret keys never stored in database, returned once only for immediate use
-- ✅ **Comprehensive test suite**: 28 tests covering all scenarios including error handling and multi-session flows
-- ✅ **Dependency injection**: Clean integration with existing FastAPI architecture
-- ✅ **Production-ready configuration**: Tigris credentials properly configured for tenant machines
-
-🗄️ **Secure Database Schema:**
-
-```sql
-CREATE TABLE tenant_mount_credentials (
-  id UUID PRIMARY KEY,
-  tenant_id UUID REFERENCES tenant(id),
-  access_key VARCHAR(255) NOT NULL,
-  -- secret_key REMOVED - never store secrets (security best practice)
-  policy_arn VARCHAR(255) NOT NULL,           -- For Tigris IAM cleanup
-  tigris_deletion_status VARCHAR(20) DEFAULT 'pending',  -- Track cleanup
-  created_at TIMESTAMP DEFAULT NOW(),
-  updated_at TIMESTAMP DEFAULT NOW(),
-  revoked_at TIMESTAMP NULL,
-  last_used_at TIMESTAMP NULL,               -- Track usage for orphan cleanup
-  description VARCHAR(255) DEFAULT 'CLI mount credentials'
-);
-```
-
-**Security Benefits:**
-- ✅ Database breach cannot expose secrets
-- ✅ Follows "secrets don't persist" security principle
-- ✅ Meets compliance requirements (SOC2, etc.)
-- ✅ Reduced attack surface
-- ✅ CLI gets credentials once and stores securely via rclone

specs/SPEC-9-1 Follow-Ups- Conflict, Sync, and Observability.md

@@ -1,390 +0,0 @@
----
-title: 'SPEC-9-1 Follow-Ups: Conflict, Sync, and Observability'
-type: tasklist
-permalink: specs/spec-9-follow-ups-conflict-sync-and-observability
-related: specs/spec-9-multi-project-bisync
-status: revised
-revision_date: 2025-10-03
----
-
-# SPEC-9-1 Follow-Ups: Conflict, Sync, and Observability
-
-**REVISED 2025-10-03:** Simplified to leverage rclone built-ins instead of custom conflict handling.
-
-**Context:** SPEC-9 delivered multi-project bidirectional sync and a unified CLI. This follow-up focuses on **observability and safety** using rclone's built-in capabilities rather than reinventing conflict handling.
-
-**Design Philosophy: "Be Dumb Like Git"**
-- Let rclone bisync handle conflict detection (it already does this)
-- Make conflicts visible and recoverable, don't prevent them
-- Cloud is always the winner on conflict (cloud-primary model)
-- Users who want version history can just use Git locally in their sync directory
-
-**What Changed from Original Version:**
-- **Replaced:** Custom `.bmmeta` sidecars → Use rclone's `.bisync/` state tracking
-- **Replaced:** Custom conflict detection → Use rclone bisync 3-way merge
-- **Replaced:** Tombstone files → rclone delete tracking handles this
-- **Replaced:** Distributed lease → Local process lock only (document multi-device warning)
-- **Replaced:** S3 versioning service → Users just use Git locally if they want history
-- **Deferred:** SPEC-14 Git integration → Postponed to teams/multi-user features
-
-## ✅ Now 
-- [ ] **Local process lock**: Prevent concurrent bisync runs on same device (`~/.basic-memory/sync.lock`)
-- [ ] **Structured sync reports**: Parse rclone bisync output into JSON reports (creates/updates/deletes/conflicts, bytes, duration); `bm sync --report`
-- [ ] **Multi-device warning**: Document that users should not run `--watch` on multiple devices simultaneously
-- [ ] **Version control guidance**: Document pattern for users to use Git locally in their sync directory if they want version history
-- [ ] **Docs polish**: cloud-mode toggle, mount↔bisync directory isolation, conflict semantics, quick start, migration guide, short demo clip/GIF
-
-## 🔜 Next
-- [ ] **Observability commands**: `bm conflicts list`, `bm sync history` to view sync reports and conflicts
-- [ ] **Conflict resolution UI**: `bm conflicts resolve <file>` to interactively pick winner from conflict files
-- [ ] **Selective sync**: allow include/exclude by project; per-project profile (safe/balanced/fast)
-
-## 🧭 Later
-- [ ] **Near real-time sync**: File watcher → targeted `rclone copy` for individual files (keep bisync as backstop)
-- [ ] **Sharing / scoped tokens**: cross-tenant/project access
-- [ ] **Bandwidth controls & backpressure**: policy for large repos
-- [ ] **Client-side encryption (optional)**: with clear trade-offs
-
-## 📏 Acceptance criteria (for "Now" items)
-- [ ] Local process lock prevents concurrent bisync runs on same device
-- [ ] rclone bisync conflict files visible and documented (`file.conflict1.md`, `file.conflict2.md`)
-- [ ] `bm sync --report` generates parsable JSON with sync statistics
-- [ ] Documentation clearly warns about multi-device `--watch` mode
-- [ ] Documentation shows users how to use Git locally for version history
-
-## What We're NOT Building (Deferred to rclone)
-- ❌ Custom `.bmmeta` sidecars (rclone tracks state in `.bisync/` workdir)
-- ❌ Custom conflict detection (rclone bisync already does 3-way merge detection)
-- ❌ Tombstone files (S3 versioning + rclone delete tracking handles this)
-- ❌ Distributed lease (low probability issue, rclone detects state divergence)
-- ❌ Rename/move tracking (rclone has size+modtime heuristics built-in)
-
-## Implementation Summary
-
-**Current State (SPEC-9):**
-- ✅ rclone bisync with 3 profiles (safe/balanced/fast)
-- ✅ `--max-delete` safety limits (10/25/50 files)
-- ✅ `--conflict-resolve=newer` for auto-resolution
-- ✅ Watch mode: `bm sync --watch` (60s intervals)
-- ✅ Integrity checking: `bm cloud check`
-- ✅ Mount vs bisync directory isolation
-
-**What's Needed (This Spec):**
-1. **Process lock** - Simple file-based lock in `~/.basic-memory/sync.lock`
-2. **Sync reports** - Parse rclone output, save to `~/.basic-memory/sync-history/`
-3. **Documentation** - Multi-device warnings, conflict resolution workflow, Git usage pattern
-
-**User Model:**
-- Cloud is always the winner on conflict (cloud-primary)
-- rclone creates `.conflict` files for divergent edits
-- Users who want version history just use Git in their local sync directory
-- Users warned: don't run `--watch` on multiple devices
-
-## Decision Rationale & Trade-offs
-
-### Why Trust rclone Instead of Custom Conflict Handling?
-
-**rclone bisync already provides:**
-- 3-way merge detection (compares local, remote, and last-known state)
-- File state tracking in `.bisync/` workdir (hashes, modtimes)
-- Automatic conflict file creation: `file.conflict1.md`, `file.conflict2.md`
-- Rename detection via size+modtime heuristics
-- Delete tracking (prevents resurrection of deleted files)
-- Battle-tested with extensive edge case handling
-
-**What we'd have to build with custom approach:**
-- Per-file metadata tracking (`.bmmeta` sidecars)
-- 3-way diff algorithm
-- Conflict detection logic
-- Tombstone files for deletes
-- Rename/move detection
-- Testing for all edge cases
-
-**Decision:** Use what rclone already does well. Don't reinvent the wheel.
-
-### Why Let Users Use Git Locally Instead of Building Versioning?
-
-**The simplest solution: Just use Git**
-
-Users who want version history can literally just use Git in their sync directory:
-
-```bash
-cd ~/basic-memory-cloud-sync/
-git init
-git add .
-git commit -m "backup"
-
-# Push to their own GitHub if they want
-git remote add origin git@github.com:user/my-knowledge.git
-git push
-```
-
-**Why this is perfect:**
-- ✅ We build nothing
-- ✅ Users who want Git... just use Git
-- ✅ Users who don't care... don't need to
-- ✅ rclone bisync already handles sync conflicts
-- ✅ Users own their data, they can version it however they want (Git, Time Machine, etc.)
-
-**What we'd have to build for S3 versioning:**
-- API to enable versioning on Tigris buckets
-  - **Problem**: Tigris doesn't support S3 bucket versioning
-- Restore commands: `bm cloud restore --version-id`
-- Version listing: `bm cloud versions <path>`
-- Lifecycle policies for version retention
-- Documentation and user education
-
-**What we'd have to build for SPEC-14 Git integration:**
-- Committer service (daemon watching `/app/data/`)
-- Puller service (webhook handler for GitHub pushes)
-- Git LFS for large files
-- Loop prevention between Git ↔ bisync ↔ local
-- Merge conflict handling at TWO layers (rclone + Git)
-- Webhook infrastructure and monitoring
-
-**Decision:** Don't build version control. Document the pattern. "The easiest problem to solve is the one you avoid."
-
-**When to revisit:** Teams/multi-user features where server-side version control becomes necessary for collaboration.
-
-### Why No Distributed Lease?
-
-**Low probability issue:**
-- Requires user to manually run `bm sync` on multiple devices at exact same time
-- Most users run `--watch` on one primary device
-- rclone bisync detects state divergence and fails safely
-
-**Safety nets in place:**
-- Local process lock prevents concurrent runs on same device
-- rclone bisync aborts if bucket state changed during sync
-- S3 versioning recovers from any overwrites
-- Documentation warns against multi-device `--watch`
-
-**Failure mode:**
-```bash
-# Device A and B sync simultaneously
-Device A: bm sync → succeeds
-Device B: bm sync → "Error: path has changed, run --resync"
-
-# User fixes with resync
-Device B: bm sync --resync → establishes new baseline
-```
-
-**Decision:** Document the issue, add local lock, defer distributed coordination until users report actual problems.
-
-### Cloud-Primary Conflict Model
-
-**User mental model:**
-- Cloud is the source of truth (like Dropbox/iCloud)
-- Local is working copy
-- On conflict: cloud wins, local edits → `.conflict` file
-- User manually picks winner
-
-**Why this works:**
-- Simpler than bidirectional merge (no automatic resolution risk)
-- Matches user expectations from Dropbox
-- S3 versioning provides safety net for overwrites
-- Clear recovery path: restore from S3 version if needed
-
-**Example workflow:**
-```bash
-# Edit file on Device A and Device B while offline
-# Both devices come online and sync
-
-Device A: bm sync
-# → Pushes to cloud first, becomes canonical version
-
-Device B: bm sync
-# → Detects conflict
-# → Cloud version: work/notes.md
-# → Local version: work/notes.md.conflict1
-# → User manually merges or picks winner
-
-# Restore if needed
-bm cloud restore work/notes.md --version-id abc123
-```
-
-## Implementation Details
-
-### 1. Local Process Lock
-
-```python
-# ~/.basic-memory/sync.lock
-import os
-import psutil
-from pathlib import Path
-
-class SyncLock:
-    def __init__(self):
-        self.lock_file = Path.home() / '.basic-memory' / 'sync.lock'
-
-    def acquire(self):
-        if self.lock_file.exists():
-            pid = int(self.lock_file.read_text())
-            if psutil.pid_exists(pid):
-                raise BisyncError(
-                    f"Sync already running (PID {pid}). "
-                    f"Wait for completion or kill stale process."
-                )
-            # Stale lock, remove it
-            self.lock_file.unlink()
-
-        self.lock_file.write_text(str(os.getpid()))
-
-    def release(self):
-        if self.lock_file.exists():
-            self.lock_file.unlink()
-
-    def __enter__(self):
-        self.acquire()
-        return self
-
-    def __exit__(self, *args):
-        self.release()
-
-# Usage
-with SyncLock():
-    run_rclone_bisync()
-```
-
-### 3. Sync Report Parsing
-
-```python
-# Parse rclone bisync output
-import json
-from datetime import datetime
-from pathlib import Path
-
-def parse_sync_report(rclone_output: str, duration: float, exit_code: int) -> dict:
-    """Parse rclone bisync output into structured report."""
-
-    # rclone bisync outputs lines like:
-    # "Synching Path1 /local/path with Path2 remote:bucket"
-    # "- Path1    File was copied to Path2"
-    # "Bisync successful"
-
-    report = {
-        "timestamp": datetime.now().isoformat(),
-        "duration_seconds": duration,
-        "exit_code": exit_code,
-        "success": exit_code == 0,
-        "files_created": 0,
-        "files_updated": 0,
-        "files_deleted": 0,
-        "conflicts": [],
-        "errors": []
-    }
-
-    for line in rclone_output.split('\n'):
-        if 'was copied to' in line:
-            report['files_created'] += 1
-        elif 'was updated in' in line:
-            report['files_updated'] += 1
-        elif 'was deleted from' in line:
-            report['files_deleted'] += 1
-        elif '.conflict' in line:
-            report['conflicts'].append(line.strip())
-        elif 'ERROR' in line:
-            report['errors'].append(line.strip())
-
-    return report
-
-def save_sync_report(report: dict):
-    """Save sync report to history."""
-    history_dir = Path.home() / '.basic-memory' / 'sync-history'
-    history_dir.mkdir(parents=True, exist_ok=True)
-
-    timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
-    report_file = history_dir / f'{timestamp}.json'
-
-    report_file.write_text(json.dumps(report, indent=2))
-
-# Usage in run_bisync()
-start_time = time.time()
-result = subprocess.run(bisync_cmd, capture_output=True, text=True)
-duration = time.time() - start_time
-
-report = parse_sync_report(result.stdout, duration, result.returncode)
-save_sync_report(report)
-
-if report['conflicts']:
-    console.print(f"[yellow]⚠ {len(report['conflicts'])} conflict(s) detected[/yellow]")
-    console.print("[dim]Run 'bm conflicts list' to view[/dim]")
-```
-
-### 4. User Commands
-
-```bash
-# View sync history
-bm sync history
-# → Lists recent syncs from ~/.basic-memory/sync-history/*.json
-# → Shows: timestamp, duration, files changed, conflicts, errors
-
-# View current conflicts
-bm conflicts list
-# → Scans sync directory for *.conflict* files
-# → Shows: file path, conflict versions, timestamps
-
-# Restore from S3 version
-bm cloud restore work/notes.md --version-id abc123
-# → Uses aws s3api get-object with version-id
-# → Downloads to original path
-
-bm cloud restore work/notes.md --timestamp "2025-10-03 14:30"
-# → Lists versions, finds closest to timestamp
-# → Downloads that version
-
-# List file versions
-bm cloud versions work/notes.md
-# → Uses aws s3api list-object-versions
-# → Shows: version-id, timestamp, size, author
-
-# Interactive conflict resolution
-bm conflicts resolve work/notes.md
-# → Shows both versions side-by-side
-# → Prompts: Keep local, keep cloud, merge manually, restore from S3 version
-# → Cleans up .conflict files after resolution
-```
-
-## Success Metrics & Monitoring
-
-**Phase 1 (v1) - Basic Safety:**
-- [ ] Conflict detection rate < 5% of syncs (measure in telemetry)
-- [ ] User can resolve conflicts within 5 minutes (UX testing)
-- [ ] Documentation prevents 90% of multi-device issues
-
-**Phase 2 (v2) - Observability:**
-- [ ] 80% of users check `bm sync history` when troubleshooting
-- [ ] Average time to restore from S3 version < 2 minutes
-- 
-- [ ] Conflict resolution success rate > 95%
-
-**What to measure:**
-```python
-# Telemetry in sync reports
-{
-    "conflict_rate": conflicts / total_syncs,
-    "multi_device_collisions": count_state_divergence_errors,
-    "version_restores": count_restore_operations,
-    "avg_sync_duration": sum(durations) / count,
-    "max_delete_trips": count_max_delete_aborts
-}
-```
-
-**When to add distributed lease:**
-- Multi-device collision rate > 5% of syncs
-- User complaints about state divergence errors
-- Evidence that local lock isn't sufficient
-
-**When to revisit Git (SPEC-14):**
-- Teams feature launches (multi-user collaboration)
-- Users request commit messages / audit trail
-- PR-based review workflow becomes valuable
-
-## Links
-- SPEC-9: `specs/spec-9-multi-project-bisync`
-- SPEC-14: `specs/spec-14-cloud-git-versioning` (deferred in favor of S3 versioning)
-- rclone bisync docs: https://rclone.org/bisync/
-- Tigris S3 versioning: https://www.tigrisdata.com/docs/buckets/versioning/
-
----
-**Owner:** <assign>  |  **Review cadence:** weekly in standup  |  **Last updated:** 2025-10-03

src/basic_memory/__init__.py

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

src/basic_memory/alembic/alembic.ini

@@ -1,119 +0,0 @@
-# A generic, single database configuration.
-
-[alembic]
-# path to migration scripts
-# Use forward slashes (/) also on windows to provide an os agnostic path
-script_location = .
-
-# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
-# Uncomment the line below if you want the files to be prepended with date and time
-# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
-# for all available tokens
-# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
-
-# sys.path path, will be prepended to sys.path if present.
-# defaults to the current working directory.
-prepend_sys_path = .
-
-# timezone to use when rendering the date within the migration file
-# as well as the filename.
-# If specified, requires the python>=3.9 or backports.zoneinfo library and tzdata library.
-# Any required deps can installed by adding `alembic[tz]` to the pip requirements
-# string value is passed to ZoneInfo()
-# leave blank for localtime
-# timezone =
-
-# max length of characters to apply to the "slug" field
-# truncate_slug_length = 40
-
-# set to 'true' to run the environment during
-# the 'revision' command, regardless of autogenerate
-# revision_environment = false
-
-# set to 'true' to allow .pyc and .pyo files without
-# a source .py file to be detected as revisions in the
-# versions/ directory
-# sourceless = false
-
-# version location specification; This defaults
-# to migrations/versions.  When using multiple version
-# directories, initial revisions must be specified with --version-path.
-# The path separator used here should be the separator specified by "version_path_separator" below.
-# version_locations = %(here)s/bar:%(here)s/bat:migrations/versions
-
-# version path separator; As mentioned above, this is the character used to split
-# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
-# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
-# Valid values for version_path_separator are:
-#
-# version_path_separator = :
-# version_path_separator = ;
-# version_path_separator = space
-# version_path_separator = newline
-#
-# Use os.pathsep. Default configuration used for new projects.
-version_path_separator = os
-
-# set to 'true' to search source files recursively
-# in each "version_locations" directory
-# new in Alembic version 1.10
-# recursive_version_locations = false
-
-# the output encoding used when revision files
-# are written from script.py.mako
-# output_encoding = utf-8
-
-sqlalchemy.url = driver://user:pass@localhost/dbname
-
-
-[post_write_hooks]
-# post_write_hooks defines scripts or Python functions that are run
-# on newly generated revision scripts.  See the documentation for further
-# detail and examples
-
-# format using "black" - use the console_scripts runner, against the "black" entrypoint
-# hooks = black
-# black.type = console_scripts
-# black.entrypoint = black
-# black.options = -l 79 REVISION_SCRIPT_FILENAME
-
-# lint with attempts to fix using "ruff" - use the exec runner, execute a binary
-# hooks = ruff
-# ruff.type = exec
-# ruff.executable = %(here)s/.venv/bin/ruff
-# ruff.options = --fix REVISION_SCRIPT_FILENAME
-
-# Logging configuration
-[loggers]
-keys = root,sqlalchemy,alembic
-
-[handlers]
-keys = console
-
-[formatters]
-keys = generic
-
-[logger_root]
-level = WARNING
-handlers = console
-qualname =
-
-[logger_sqlalchemy]
-level = WARNING
-handlers =
-qualname = sqlalchemy.engine
-
-[logger_alembic]
-level = INFO
-handlers =
-qualname = alembic
-
-[handler_console]
-class = StreamHandler
-args = (sys.stderr,)
-level = NOTSET
-formatter = generic
-
-[formatter_generic]
-format = %(levelname)-5.5s [%(name)s] %(message)s
-datefmt = %H:%M:%S

src/basic_memory/alembic/env.py

@@ -1,99 +0,0 @@
-"""Alembic environment configuration."""
-
-import os
-from logging.config import fileConfig
-
-from sqlalchemy import engine_from_config
-from sqlalchemy import pool
-
-from alembic import context
-
-from basic_memory.config import ConfigManager
-
-# set config.env to "test" for pytest to prevent logging to file in utils.setup_logging()
-os.environ["BASIC_MEMORY_ENV"] = "test"
-
-# Import after setting environment variable  # 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
-
-app_config = ConfigManager().config
-# Set the SQLAlchemy URL from our app config
-sqlalchemy_url = f"sqlite:///{app_config.database_path}"
-config.set_main_option("sqlalchemy.url", sqlalchemy_url)
-
-# print(f"Using SQLAlchemy URL: {sqlalchemy_url}")
-
-# Interpret the config file for Python logging.
-if config.config_file_name is not None:
-    fileConfig(config.config_file_name)
-
-# add your model's MetaData object here
-# for 'autogenerate' support
-target_metadata = Base.metadata
-
-
-# Add this function to tell Alembic what to include/exclude
-def include_object(object, name, type_, reflected, compare_to):
-    # Ignore SQLite FTS tables
-    if type_ == "table" and name.startswith("search_index"):
-        return False
-    return True
-
-
-def run_migrations_offline() -> None:
-    """Run migrations in 'offline' mode.
-
-    This configures the context with just a URL
-    and not an Engine, though an Engine is acceptable
-    here as well.  By skipping the Engine creation
-    we don't even need a DBAPI to be available.
-
-    Calls to context.execute() here emit the given string to the
-    script output.
-    """
-    url = config.get_main_option("sqlalchemy.url")
-    context.configure(
-        url=url,
-        target_metadata=target_metadata,
-        literal_binds=True,
-        dialect_opts={"paramstyle": "named"},
-        include_object=include_object,
-        render_as_batch=True,
-    )
-
-    with context.begin_transaction():
-        context.run_migrations()
-
-
-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.
-    """
-    connectable = engine_from_config(
-        config.get_section(config.config_ini_section, {}),
-        prefix="sqlalchemy.",
-        poolclass=pool.NullPool,
-    )
-
-    with connectable.connect() as connection:
-        context.configure(
-            connection=connection,
-            target_metadata=target_metadata,
-            include_object=include_object,
-            render_as_batch=True,
-        )
-
-        with context.begin_transaction():
-            context.run_migrations()
-
-
-if context.is_offline_mode():
-    run_migrations_offline()
-else:
-    run_migrations_online()

src/basic_memory/alembic/migrations.py

@@ -1,24 +0,0 @@
-"""Functions for managing database migrations."""
-
-from pathlib import Path
-from loguru import logger
-from alembic.config import Config
-from alembic import command
-
-
-def get_alembic_config() -> Config:  # pragma: no cover
-    """Get alembic config with correct paths."""
-    migrations_path = Path(__file__).parent
-    alembic_ini = migrations_path / "alembic.ini"
-
-    config = Config(alembic_ini)
-    config.set_main_option("script_location", str(migrations_path))
-    return config
-
-
-def reset_database():  # pragma: no cover
-    """Drop and recreate all tables."""
-    logger.info("Resetting database...")
-    config = get_alembic_config()
-    command.downgrade(config, "base")
-    command.upgrade(config, "head")

src/basic_memory/alembic/script.py.mako

@@ -1,26 +0,0 @@
-"""${message}
-
-Revision ID: ${up_revision}
-Revises: ${down_revision | comma,n}
-Create Date: ${create_date}
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-${imports if imports else ""}
-
-# revision identifiers, used by Alembic.
-revision: str = ${repr(up_revision)}
-down_revision: Union[str, None] = ${repr(down_revision)}
-branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
-depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
-
-
-def upgrade() -> None:
-    ${upgrades if upgrades else "pass"}
-
-
-def downgrade() -> None:
-    ${downgrades if downgrades else "pass"}

src/basic_memory/alembic/versions/3dae7c7b1564_initial_schema.py

@@ -1,93 +0,0 @@
-"""initial schema
-
-Revision ID: 3dae7c7b1564
-Revises:
-Create Date: 2025-02-12 21:23:00.336344
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = "3dae7c7b1564"
-down_revision: Union[str, None] = None
-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! ###
-    op.create_table(
-        "entity",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("title", sa.String(), nullable=False),
-        sa.Column("entity_type", sa.String(), nullable=False),
-        sa.Column("entity_metadata", sa.JSON(), nullable=True),
-        sa.Column("content_type", sa.String(), nullable=False),
-        sa.Column("permalink", sa.String(), nullable=False),
-        sa.Column("file_path", sa.String(), nullable=False),
-        sa.Column("checksum", sa.String(), nullable=True),
-        sa.Column("created_at", sa.DateTime(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(), nullable=False),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("permalink", name="uix_entity_permalink"),
-    )
-    op.create_index("ix_entity_created_at", "entity", ["created_at"], unique=False)
-    op.create_index(op.f("ix_entity_file_path"), "entity", ["file_path"], unique=True)
-    op.create_index(op.f("ix_entity_permalink"), "entity", ["permalink"], unique=True)
-    op.create_index("ix_entity_title", "entity", ["title"], unique=False)
-    op.create_index("ix_entity_type", "entity", ["entity_type"], unique=False)
-    op.create_index("ix_entity_updated_at", "entity", ["updated_at"], unique=False)
-    op.create_table(
-        "observation",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("entity_id", sa.Integer(), nullable=False),
-        sa.Column("content", sa.Text(), nullable=False),
-        sa.Column("category", sa.String(), nullable=False),
-        sa.Column("context", sa.Text(), nullable=True),
-        sa.Column("tags", sa.JSON(), server_default="[]", nullable=True),
-        sa.ForeignKeyConstraint(["entity_id"], ["entity.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("ix_observation_category", "observation", ["category"], unique=False)
-    op.create_index("ix_observation_entity_id", "observation", ["entity_id"], unique=False)
-    op.create_table(
-        "relation",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("from_id", sa.Integer(), nullable=False),
-        sa.Column("to_id", sa.Integer(), nullable=True),
-        sa.Column("to_name", sa.String(), nullable=False),
-        sa.Column("relation_type", sa.String(), nullable=False),
-        sa.Column("context", sa.Text(), nullable=True),
-        sa.ForeignKeyConstraint(["from_id"], ["entity.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["to_id"], ["entity.id"], ondelete="CASCADE"),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("from_id", "to_id", "relation_type", name="uix_relation"),
-    )
-    op.create_index("ix_relation_from_id", "relation", ["from_id"], unique=False)
-    op.create_index("ix_relation_to_id", "relation", ["to_id"], unique=False)
-    op.create_index("ix_relation_type", "relation", ["relation_type"], unique=False)
-    # ### end Alembic commands ###
-
-
-def downgrade() -> None:
-    # ### commands auto generated by Alembic - please adjust! ###
-    op.drop_index("ix_relation_type", table_name="relation")
-    op.drop_index("ix_relation_to_id", table_name="relation")
-    op.drop_index("ix_relation_from_id", table_name="relation")
-    op.drop_table("relation")
-    op.drop_index("ix_observation_entity_id", table_name="observation")
-    op.drop_index("ix_observation_category", table_name="observation")
-    op.drop_table("observation")
-    op.drop_index("ix_entity_updated_at", table_name="entity")
-    op.drop_index("ix_entity_type", table_name="entity")
-    op.drop_index("ix_entity_title", table_name="entity")
-    op.drop_index(op.f("ix_entity_permalink"), table_name="entity")
-    op.drop_index(op.f("ix_entity_file_path"), table_name="entity")
-    op.drop_index("ix_entity_created_at", table_name="entity")
-    op.drop_table("entity")
-    # ### end Alembic commands ###

src/basic_memory/alembic/versions/502b60eaa905_remove_required_from_entity_permalink.py

@@ -1,51 +0,0 @@
-"""remove required from entity.permalink
-
-Revision ID: 502b60eaa905
-Revises: b3c3938bacdb
-Create Date: 2025-02-24 13:33:09.790951
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = "502b60eaa905"
-down_revision: Union[str, None] = "b3c3938bacdb"
-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.alter_column("permalink", existing_type=sa.VARCHAR(), nullable=True)
-        batch_op.drop_index("ix_entity_permalink")
-        batch_op.create_index(batch_op.f("ix_entity_permalink"), ["permalink"], unique=False)
-        batch_op.drop_constraint("uix_entity_permalink", type_="unique")
-        batch_op.create_index(
-            "uix_entity_permalink",
-            ["permalink"],
-            unique=True,
-            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
-        )
-
-    # ### 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_index(
-            "uix_entity_permalink",
-            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
-        )
-        batch_op.create_unique_constraint("uix_entity_permalink", ["permalink"])
-        batch_op.drop_index(batch_op.f("ix_entity_permalink"))
-        batch_op.create_index("ix_entity_permalink", ["permalink"], unique=1)
-        batch_op.alter_column("permalink", existing_type=sa.VARCHAR(), nullable=False)
-
-    # ### end Alembic commands ###

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

@@ -1,108 +0,0 @@
-"""add projects table
-
-Revision ID: 5fe1ab1ccebe
-Revises: cc7172b46608
-Create Date: 2025-05-14 09:05:18.214357
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = "5fe1ab1ccebe"
-down_revision: Union[str, None] = "cc7172b46608"
-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! ###
-    op.create_table(
-        "project",
-        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),
-        sa.Column("created_at", sa.DateTime(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(), nullable=False),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("is_default"),
-        sa.UniqueConstraint("name"),
-        sa.UniqueConstraint("permalink"),
-        if_not_exists=True,
-    )
-    with op.batch_alter_table("project", schema=None) as batch_op:
-        batch_op.create_index(
-            "ix_project_created_at", ["created_at"], unique=False, if_not_exists=True
-        )
-        batch_op.create_index("ix_project_name", ["name"], unique=True, if_not_exists=True)
-        batch_op.create_index("ix_project_path", ["path"], unique=False, if_not_exists=True)
-        batch_op.create_index(
-            "ix_project_permalink", ["permalink"], unique=True, if_not_exists=True
-        )
-        batch_op.create_index(
-            "ix_project_updated_at", ["updated_at"], unique=False, if_not_exists=True
-        )
-
-    with op.batch_alter_table("entity", schema=None) as batch_op:
-        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"),
-        )
-        batch_op.drop_index("ix_entity_file_path")
-        batch_op.create_index(batch_op.f("ix_entity_file_path"), ["file_path"], unique=False)
-        batch_op.create_index("ix_entity_project_id", ["project_id"], unique=False)
-        batch_op.create_index(
-            "uix_entity_file_path_project", ["file_path", "project_id"], unique=True
-        )
-        batch_op.create_index(
-            "uix_entity_permalink_project",
-            ["permalink", "project_id"],
-            unique=True,
-            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
-        )
-        batch_op.create_foreign_key("fk_entity_project_id", "project", ["project_id"], ["id"])
-
-    # drop the search index table. it will be recreated
-    op.drop_table("search_index")
-
-    # ### 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("fk_entity_project_id", type_="foreignkey")
-        batch_op.drop_index(
-            "uix_entity_permalink_project",
-            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
-        )
-        batch_op.drop_index("uix_entity_file_path_project")
-        batch_op.drop_index("ix_entity_project_id")
-        batch_op.drop_index(batch_op.f("ix_entity_file_path"))
-        batch_op.create_index("ix_entity_file_path", ["file_path"], unique=1)
-        batch_op.create_index(
-            "uix_entity_permalink",
-            ["permalink"],
-            unique=1,
-            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
-        )
-        batch_op.drop_column("project_id")
-
-    with op.batch_alter_table("project", schema=None) as batch_op:
-        batch_op.drop_index("ix_project_updated_at")
-        batch_op.drop_index("ix_project_permalink")
-        batch_op.drop_index("ix_project_path")
-        batch_op.drop_index("ix_project_name")
-        batch_op.drop_index("ix_project_created_at")
-
-    op.drop_table("project")
-    # ### end Alembic commands ###

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

@@ -1,104 +0,0 @@
-"""project constraint fix
-
-Revision ID: 647e7a75e2cd
-Revises: 5fe1ab1ccebe
-Create Date: 2025-06-03 12:48:30.162566
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = "647e7a75e2cd"
-down_revision: Union[str, None] = "5fe1ab1ccebe"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    """Remove the problematic UNIQUE constraint on is_default column.
-
-    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.
-    """
-    # For SQLite, we need to recreate the table without the UNIQUE constraint
-    # Create a new table without the UNIQUE constraint on is_default
-    op.create_table(
-        "project_new",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("name", sa.String(), nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        sa.Column("permalink", sa.String(), nullable=False),
-        sa.Column("path", sa.String(), nullable=False),
-        sa.Column("is_active", sa.Boolean(), nullable=False),
-        sa.Column("is_default", sa.Boolean(), nullable=True),  # No UNIQUE constraint!
-        sa.Column("created_at", sa.DateTime(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(), nullable=False),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("name"),
-        sa.UniqueConstraint("permalink"),
-    )
-
-    # Copy data from old table to new table
-    op.execute("INSERT INTO project_new SELECT * FROM project")
-
-    # Drop the old table
-    op.drop_table("project")
-
-    # Rename the new table
-    op.rename_table("project_new", "project")
-
-    # Recreate the indexes
-    with op.batch_alter_table("project", schema=None) as batch_op:
-        batch_op.create_index("ix_project_created_at", ["created_at"], unique=False)
-        batch_op.create_index("ix_project_name", ["name"], unique=True)
-        batch_op.create_index("ix_project_path", ["path"], unique=False)
-        batch_op.create_index("ix_project_permalink", ["permalink"], unique=True)
-        batch_op.create_index("ix_project_updated_at", ["updated_at"], unique=False)
-
-
-def downgrade() -> None:
-    """Add back the UNIQUE constraint on is_default column.
-
-    WARNING: This will break project creation again if multiple projects
-    have is_default=FALSE.
-    """
-    # Recreate the table with the UNIQUE constraint
-    op.create_table(
-        "project_old",
-        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),
-        sa.Column("created_at", sa.DateTime(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(), nullable=False),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("is_default"),  # Add back the problematic constraint
-        sa.UniqueConstraint("name"),
-        sa.UniqueConstraint("permalink"),
-    )
-
-    # Copy data (this may fail if multiple FALSE values exist)
-    op.execute("INSERT INTO project_old SELECT * FROM project")
-
-    # Drop the current table and rename
-    op.drop_table("project")
-    op.rename_table("project_old", "project")
-
-    # Recreate 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)

src/basic_memory/alembic/versions/a1b2c3d4e5f6_fix_project_foreign_keys.py

@@ -1,49 +0,0 @@
-"""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/b3c3938bacdb_relation_to_name_unique_index.py

@@ -1,44 +0,0 @@
-"""relation to_name unique index
-
-Revision ID: b3c3938bacdb
-Revises: 3dae7c7b1564
-Create Date: 2025-02-22 14:59:30.668466
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-
-
-# revision identifiers, used by Alembic.
-revision: str = "b3c3938bacdb"
-down_revision: Union[str, None] = "3dae7c7b1564"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # SQLite doesn't support constraint changes through ALTER
-    # Need to recreate table with desired constraints
-    with op.batch_alter_table("relation") as batch_op:
-        # Drop existing unique constraint
-        batch_op.drop_constraint("uix_relation", type_="unique")
-
-        # Add new constraints
-        batch_op.create_unique_constraint(
-            "uix_relation_from_id_to_id", ["from_id", "to_id", "relation_type"]
-        )
-        batch_op.create_unique_constraint(
-            "uix_relation_from_id_to_name", ["from_id", "to_name", "relation_type"]
-        )
-
-
-def downgrade() -> None:
-    with op.batch_alter_table("relation") as batch_op:
-        # Drop new constraints
-        batch_op.drop_constraint("uix_relation_from_id_to_name", type_="unique")
-        batch_op.drop_constraint("uix_relation_from_id_to_id", type_="unique")
-
-        # Restore original constraint
-        batch_op.create_unique_constraint("uix_relation", ["from_id", "to_id", "relation_type"])

src/basic_memory/alembic/versions/cc7172b46608_update_search_index_schema.py

@@ -1,100 +0,0 @@
-"""Update search index schema
-
-Revision ID: cc7172b46608
-Revises: 502b60eaa905
-Create Date: 2025-02-28 18:48:23.244941
-
-"""
-
-from typing import Sequence, Union
-
-from alembic import op
-
-
-# revision identifiers, used by Alembic.
-revision: str = "cc7172b46608"
-down_revision: Union[str, None] = "502b60eaa905"
-branch_labels: Union[str, Sequence[str], None] = None
-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."""
-
-    # First, drop the existing search_index table
-    op.execute("DROP TABLE IF EXISTS search_index")
-
-    # Create new search_index with updated schema
-    op.execute("""
-    CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
-        -- Core entity fields
-        id UNINDEXED,          -- Row ID
-        title,                 -- Title for searching
-        content_stems,         -- Main searchable content split into stems
-        content_snippet,       -- File content snippet for display
-        permalink,             -- Stable identifier (now indexed for path search)
-        file_path UNINDEXED,   -- Physical location
-        type UNINDEXED,        -- entity/relation/observation
-        
-        -- Relation fields 
-        from_id UNINDEXED,     -- Source entity
-        to_id UNINDEXED,       -- Target entity
-        relation_type UNINDEXED, -- Type of relation
-        
-        -- Observation fields
-        entity_id UNINDEXED,   -- Parent entity
-        category UNINDEXED,    -- Observation category
-        
-        -- Common fields
-        metadata UNINDEXED,    -- JSON metadata
-        created_at UNINDEXED,  -- Creation timestamp
-        updated_at UNINDEXED,  -- Last update
-        
-        -- Configuration
-        tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
-        prefix='1,2,3,4'                    -- Support longer prefixes for paths
-    );
-    """)
-
-
-def downgrade() -> None:
-    """Downgrade database schema to use old search index."""
-    # Drop the updated search_index table
-    op.execute("DROP TABLE IF EXISTS search_index")
-
-    # Recreate the original search_index schema
-    op.execute("""
-    CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
-        -- Core entity fields
-        id UNINDEXED,          -- Row ID
-        title,                 -- Title for searching
-        content,               -- Main searchable content
-        permalink,             -- Stable identifier (now indexed for path search)
-        file_path UNINDEXED,   -- Physical location
-        type UNINDEXED,        -- entity/relation/observation
-        
-        -- Relation fields 
-        from_id UNINDEXED,     -- Source entity
-        to_id UNINDEXED,       -- Target entity
-        relation_type UNINDEXED, -- Type of relation
-        
-        -- Observation fields
-        entity_id UNINDEXED,   -- Parent entity
-        category UNINDEXED,    -- Observation category
-        
-        -- Common fields
-        metadata UNINDEXED,    -- JSON metadata
-        created_at UNINDEXED,  -- Creation timestamp
-        updated_at UNINDEXED,  -- Last update
-        
-        -- Configuration
-        tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
-        prefix='1,2,3,4'                    -- Support longer prefixes for paths
-    );
-    """)
-
-    # Print instruction to manually reindex after migration
-    print("\n------------------------------------------------------------------")
-    print("IMPORTANT: After downgrade completes, manually run the reindex command:")
-    print("basic-memory sync")
-    print("------------------------------------------------------------------\n")

src/basic_memory/api/__init__.py

@@ -1,5 +0,0 @@
-"""Basic Memory API module."""
-
-from .app import app
-
-__all__ = ["app"]

src/basic_memory/api/app.py

@@ -1,98 +0,0 @@
-"""FastAPI application for basic-memory knowledge graph API."""
-
-import asyncio
-from contextlib import asynccontextmanager
-
-from fastapi import FastAPI, HTTPException
-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.routers import (
-    directory_router,
-    importer_router,
-    knowledge,
-    management,
-    memory,
-    project,
-    resource,
-    search,
-    prompt_router,
-)
-from basic_memory.config import ConfigManager
-from basic_memory.services.initialization import initialize_file_sync, initialize_app
-
-
-@asynccontextmanager
-async def lifespan(app: FastAPI):  # pragma: no cover
-    """Lifecycle manager for the FastAPI app. Not called in stdio mcp mode"""
-
-    app_config = ConfigManager().config
-    logger.info("Starting Basic Memory API")
-
-    await initialize_app(app_config)
-
-    # Cache database connections in app state for performance
-    logger.info("Initializing database and caching connections...")
-    engine, session_maker = await db.get_or_create_db(app_config.database_path)
-    app.state.engine = engine
-    app.state.session_maker = session_maker
-    logger.info("Database connections cached in app state")
-
-    logger.info(f"Sync changes enabled: {app_config.sync_changes}")
-    if app_config.sync_changes:
-        # start file sync task in background
-        app.state.sync_task = asyncio.create_task(initialize_file_sync(app_config))
-    else:
-        logger.info("Sync changes disabled. Skipping file sync service.")
-
-    # proceed with startup
-    yield
-
-    logger.info("Shutting down Basic Memory API")
-    if app.state.sync_task:
-        logger.info("Stopping sync...")
-        app.state.sync_task.cancel()  # pyright: ignore
-
-    await db.shutdown_db()
-
-
-# Initialize FastAPI app
-app = FastAPI(
-    title="Basic Memory API",
-    description="Knowledge graph API for basic-memory",
-    version=version,
-    lifespan=lifespan,
-)
-
-
-# Include routers
-app.include_router(knowledge.router, prefix="/{project}")
-app.include_router(memory.router, prefix="/{project}")
-app.include_router(resource.router, prefix="/{project}")
-app.include_router(search.router, prefix="/{project}")
-app.include_router(project.project_router, prefix="/{project}")
-app.include_router(directory_router.router, prefix="/{project}")
-app.include_router(prompt_router.router, prefix="/{project}")
-app.include_router(importer_router.router, prefix="/{project}")
-
-# Project resource router works accross 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
-    logger.exception(
-        "API unhandled exception",
-        url=str(request.url),
-        method=request.method,
-        client=request.client.host if request.client else None,
-        path=request.url.path,
-        error_type=type(exc).__name__,
-        error=str(exc),
-    )
-    return await http_exception_handler(request, HTTPException(status_code=500, detail=str(exc)))

src/basic_memory/api/routers/__init__.py

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

src/basic_memory/api/routers/directory_router.py

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

src/basic_memory/api/routers/importer_router.py

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

src/basic_memory/api/routers/knowledge_router.py

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

src/basic_memory/api/routers/management_router.py

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

src/basic_memory/api/routers/memory_router.py

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

src/basic_memory/api/routers/project_router.py

@@ -1,338 +0,0 @@
-"""Router for project management."""
-
-import os
-from fastapi import APIRouter, HTTPException, Path, Body, BackgroundTasks
-from typing import Optional
-from loguru import logger
-
-from basic_memory.deps import (
-    ProjectConfigDep,
-    ProjectServiceDep,
-    ProjectPathDep,
-    SyncServiceDep,
-)
-from basic_memory.schemas import ProjectInfoResponse, SyncReportResponse
-from basic_memory.schemas.project_info import (
-    ProjectList,
-    ProjectItem,
-    ProjectInfoRequest,
-    ProjectStatusResponse,
-)
-
-# Router for resources in a specific project
-# The ProjectPathDep is used in the path as a prefix, so the request path is like /{project}/project/info
-project_router = APIRouter(prefix="/project", tags=["project"])
-
-# Router for managing project resources
-project_resource_router = APIRouter(prefix="/projects", tags=["project_management"])
-
-
-@project_router.get("/info", response_model=ProjectInfoResponse)
-async def get_project_info(
-    project_service: ProjectServiceDep,
-    project: ProjectPathDep,
-) -> ProjectInfoResponse:
-    """Get comprehensive information about the specified Basic Memory project."""
-    return await project_service.get_project_info(project)
-
-
-@project_router.get("/item", response_model=ProjectItem)
-async def get_project(
-    project_service: ProjectServiceDep,
-    project: ProjectPathDep,
-) -> ProjectItem:
-    """Get bassic info about the specified Basic Memory project."""
-    found_project = await project_service.get_project(project)
-    if not found_project:
-        raise HTTPException(
-            status_code=404, detail=f"Project: '{project}' does not exist"
-        )  # pragma: no cover
-
-    return ProjectItem(
-        name=found_project.name,
-        path=found_project.path,
-        is_default=found_project.is_default or False,
-    )
-
-
-# Update a project
-@project_router.patch("/{name}", response_model=ProjectStatusResponse)
-async def update_project(
-    project_service: ProjectServiceDep,
-    name: str = Path(..., description="Name of the project to update"),
-    path: Optional[str] = Body(None, description="New absolute path for the project"),
-    is_active: Optional[bool] = Body(None, description="Status of the project (active/inactive)"),
-) -> ProjectStatusResponse:
-    """Update a project's information in configuration and database.
-
-    Args:
-        name: The name of the project to update
-        path: Optional new absolute path for the project
-        is_active: Optional status update for the project
-
-    Returns:
-        Response confirming the project was updated
-    """
-    try:
-        # Validate that path is absolute if provided
-        if path and not os.path.isabs(path):
-            raise HTTPException(status_code=400, detail="Path must be absolute")
-
-        # Get original project info for the response
-        old_project_info = ProjectItem(
-            name=name,
-            path=project_service.projects.get(name, ""),
-        )
-
-        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(name, "")
-
-        return ProjectStatusResponse(
-            message=f"Project '{name}' updated successfully",
-            status="success",
-            default=(name == project_service.default_project),
-            old_project=old_project_info,
-            new_project=ProjectItem(name=name, path=updated_path),
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-# Sync project filesystem
-@project_router.post("/sync")
-async def sync_project(
-    background_tasks: BackgroundTasks,
-    sync_service: SyncServiceDep,
-    project_config: ProjectConfigDep,
-):
-    """Force 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
-
-    Returns:
-        Response confirming sync was initiated
-    """
-    background_tasks.add_task(sync_service.sync, project_config.home, project_config.name)
-    logger.info(f"Filesystem sync initiated for project: {project_config.name}")
-
-    return {
-        "status": "sync_started",
-        "message": f"Filesystem sync initiated for project '{project_config.name}'",
-    }
-
-
-@project_router.post("/status", response_model=SyncReportResponse)
-async def project_sync_status(
-    sync_service: SyncServiceDep,
-    project_config: ProjectConfigDep,
-) -> SyncReportResponse:
-    """Scan directory for changes compared to database state.
-
-    Args:
-        sync_service: Sync service for this project
-        project_config: Project configuration
-
-    Returns:
-        Scan report with details on files that need syncing
-    """
-    logger.info(f"Scanning filesystem for project: {project_config.name}")
-    sync_report = await sync_service.scan(project_config.home)
-
-    return SyncReportResponse.from_sync_report(sync_report)
-
-
-# List all available projects
-@project_resource_router.get("/projects", response_model=ProjectList)
-async def list_projects(
-    project_service: ProjectServiceDep,
-) -> ProjectList:
-    """List all configured projects.
-
-    Returns:
-        A list of all projects with metadata
-    """
-    projects = await project_service.list_projects()
-    default_project = project_service.default_project
-
-    project_items = [
-        ProjectItem(
-            name=project.name,
-            path=project.path,
-            is_default=project.is_default or False,
-        )
-        for project in projects
-    ]
-
-    return ProjectList(
-        projects=project_items,
-        default_project=default_project,
-    )
-
-
-# Add a new project
-@project_resource_router.post("/projects", response_model=ProjectStatusResponse)
-async def add_project(
-    project_data: ProjectInfoRequest,
-    project_service: ProjectServiceDep,
-) -> ProjectStatusResponse:
-    """Add a new project to configuration and database.
-
-    Args:
-        project_data: The project name and path, with option to set as default
-
-    Returns:
-        Response confirming the project was added
-    """
-    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
-        )
-
-        return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
-            message=f"Project '{project_data.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
-            ),
-        )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-# Remove a project
-@project_resource_router.delete("/{name}", response_model=ProjectStatusResponse)
-async def remove_project(
-    project_service: ProjectServiceDep,
-    name: str = Path(..., description="Name of the project to remove"),
-) -> ProjectStatusResponse:
-    """Remove a project from configuration and database.
-
-    Args:
-        name: The name of the project to remove
-
-    Returns:
-        Response confirming the project was removed
-    """
-    try:
-        old_project = await project_service.get_project(name)
-        if not old_project:  # pragma: no cover
-            raise HTTPException(
-                status_code=404, detail=f"Project: '{name}' does not exist"
-            )  # pragma: no cover
-
-        await project_service.remove_project(name)
-
-        return ProjectStatusResponse(
-            message=f"Project '{name}' removed successfully",
-            status="success",
-            default=False,
-            old_project=ProjectItem(name=old_project.name, path=old_project.path),
-            new_project=None,
-        )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-# Set a project as default
-@project_resource_router.put("/{name}/default", response_model=ProjectStatusResponse)
-async def set_default_project(
-    project_service: ProjectServiceDep,
-    name: str = Path(..., description="Name of the project to set as default"),
-) -> ProjectStatusResponse:
-    """Set a project as the default project.
-
-    Args:
-        name: The name of the project to set as default
-
-    Returns:
-        Response confirming the project was set as default
-    """
-    try:
-        # Get the old default project
-        default_name = project_service.default_project
-        default_project = await project_service.get_project(default_name)
-        if not default_project:  # pragma: no cover
-            raise HTTPException(  # pragma: no cover
-                status_code=404, detail=f"Default Project: '{default_name}' does not exist"
-            )
-
-        # get the new project
-        new_default_project = await project_service.get_project(name)
-        if not new_default_project:  # pragma: no cover
-            raise HTTPException(
-                status_code=404, detail=f"Project: '{name}' does not exist"
-            )  # pragma: no cover
-
-        await project_service.set_default_project(name)
-
-        return ProjectStatusResponse(
-            message=f"Project '{name}' set as default successfully",
-            status="success",
-            default=True,
-            old_project=ProjectItem(name=default_name, path=default_project.path),
-            new_project=ProjectItem(
-                name=name,
-                path=new_default_project.path,
-                is_default=True,
-            ),
-        )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-# Get the default project
-@project_resource_router.get("/default", response_model=ProjectItem)
-async def get_default_project(
-    project_service: ProjectServiceDep,
-) -> ProjectItem:
-    """Get the default project.
-
-    Returns:
-        Response with project default information
-    """
-    # Get the 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(name=default_project.name, path=default_project.path, is_default=True)
-
-
-# Synchronize projects between config and database
-@project_resource_router.post("/config/sync", response_model=ProjectStatusResponse)
-async def synchronize_projects(
-    project_service: ProjectServiceDep,
-) -> ProjectStatusResponse:
-    """Synchronize projects between configuration file and database.
-
-    Ensures that all projects in the configuration file exist in the database
-    and vice versa.
-
-    Returns:
-        Response confirming synchronization was completed
-    """
-    try:  # pragma: no cover
-        await project_service.synchronize_projects()
-
-        return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
-            message="Projects synchronized successfully between configuration and database",
-            status="success",
-            default=False,
-        )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))

src/basic_memory/api/routers/prompt_router.py

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

src/basic_memory/api/routers/resource_router.py

@@ -1,225 +0,0 @@
-"""Routes for getting entity content."""
-
-import tempfile
-from pathlib import Path
-from typing import Annotated
-
-from fastapi import APIRouter, HTTPException, BackgroundTasks, Body
-from fastapi.responses import FileResponse, JSONResponse
-from loguru import logger
-
-from basic_memory.deps import (
-    ProjectConfigDep,
-    LinkResolverDep,
-    SearchServiceDep,
-    EntityServiceDep,
-    FileServiceDep,
-    EntityRepositoryDep,
-)
-from basic_memory.repository.search_repository import SearchIndexRow
-from basic_memory.schemas.memory import normalize_memory_url
-from basic_memory.schemas.search import SearchQuery, SearchItemType
-from basic_memory.models.knowledge import Entity as EntityModel
-from datetime import datetime
-
-router = APIRouter(prefix="/resource", tags=["resources"])
-
-
-def get_entity_ids(item: SearchIndexRow) -> set[int]:
-    match item.type:
-        case SearchItemType.ENTITY:
-            return {item.id}
-        case SearchItemType.OBSERVATION:
-            return {item.entity_id}  # pyright: ignore [reportReturnType]
-        case SearchItemType.RELATION:
-            from_entity = item.from_id
-            to_entity = item.to_id  # pyright: ignore [reportReturnType]
-            return {from_entity, to_entity} if to_entity else {from_entity}  # pyright: ignore [reportReturnType]
-        case _:  # pragma: no cover
-            raise ValueError(f"Unexpected type: {item.type}")
-
-
-@router.get("/{identifier:path}")
-async def get_resource_content(
-    config: ProjectConfigDep,
-    link_resolver: LinkResolverDep,
-    search_service: SearchServiceDep,
-    entity_service: EntityServiceDep,
-    file_service: FileServiceDep,
-    background_tasks: BackgroundTasks,
-    identifier: str,
-    page: int = 1,
-    page_size: int = 10,
-) -> FileResponse:
-    """Get resource content by identifier: name or permalink."""
-    logger.debug(f"Getting content for: {identifier}")
-
-    # Find single entity by permalink
-    entity = await link_resolver.resolve_link(identifier)
-    results = [entity] if entity else []
-
-    # pagination for multiple results
-    limit = page_size
-    offset = (page - 1) * page_size
-
-    # search using the identifier as a permalink
-    if not results:
-        # if the identifier contains a wildcard, use GLOB search
-        query = (
-            SearchQuery(permalink_match=identifier)
-            if "*" in identifier
-            else SearchQuery(permalink=identifier)
-        )
-        search_results = await search_service.search(query, limit, offset)
-        if not search_results:
-            raise HTTPException(status_code=404, detail=f"Resource not found: {identifier}")
-
-        # get the deduplicated entities related to the search results
-        entity_ids = {id for result in search_results for id in get_entity_ids(result)}
-        results = await entity_service.get_entities_by_id(list(entity_ids))
-
-    # return single response
-    if len(results) == 1:
-        entity = results[0]
-        file_path = Path(f"{config.home}/{entity.file_path}")
-        if not file_path.exists():
-            raise HTTPException(
-                status_code=404,
-                detail=f"File not found: {file_path}",
-            )
-        return FileResponse(path=file_path)
-
-    # for multiple files, initialize a temporary file for writing the results
-    with tempfile.NamedTemporaryFile(delete=False, mode="w", suffix=".md") as tmp_file:
-        temp_file_path = tmp_file.name
-
-        for result in results:
-            # Read content for each entity
-            content = await file_service.read_entity_content(result)
-            memory_url = normalize_memory_url(result.permalink)
-            modified_date = result.updated_at.isoformat()
-            checksum = result.checksum[:8] if result.checksum else ""
-
-            # Prepare the delimited content
-            response_content = f"--- {memory_url} {modified_date} {checksum}\n"
-            response_content += f"\n{content}\n"
-            response_content += "\n"
-
-            # Write content directly to the temporary file in append mode
-            tmp_file.write(response_content)
-
-        # Ensure all content is written to disk
-        tmp_file.flush()
-
-    # Schedule the temporary file to be deleted after the response
-    background_tasks.add_task(cleanup_temp_file, temp_file_path)
-
-    # Return the file response
-    return FileResponse(path=temp_file_path)
-
-
-def cleanup_temp_file(file_path: str):
-    """Delete the temporary file."""
-    try:
-        Path(file_path).unlink()  # Deletes the file
-        logger.debug(f"Temporary file deleted: {file_path}")
-    except Exception as e:  # pragma: no cover
-        logger.error(f"Error deleting temporary file {file_path}: {e}")
-
-
-@router.put("/{file_path:path}")
-async def write_resource(
-    config: ProjectConfigDep,
-    file_service: FileServiceDep,
-    entity_repository: EntityRepositoryDep,
-    search_service: SearchServiceDep,
-    file_path: str,
-    content: Annotated[str, Body()],
-) -> JSONResponse:
-    """Write content to a file in the project.
-
-    This endpoint allows writing content directly to a file in the project.
-    Also creates an entity record and indexes the file for search.
-
-    Args:
-        file_path: Path to write to, relative to project root
-        request: Contains the content to write
-
-    Returns:
-        JSON response with file information
-    """
-    try:
-        # Get content from request body
-
-        # 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)
-
-        # Get file info
-        file_stats = file_service.file_stats(full_path)
-
-        # Determine file details
-        file_name = Path(file_path).name
-        content_type = file_service.content_type(full_path)
-
-        entity_type = "canvas" if file_path.endswith(".canvas") else "file"
-
-        # Check if entity already exists
-        existing_entity = await entity_repository.get_by_file_path(file_path)
-
-        if existing_entity:
-            # Update existing entity
-            entity = await entity_repository.update(
-                existing_entity.id,
-                {
-                    "title": file_name,
-                    "entity_type": entity_type,
-                    "content_type": content_type,
-                    "file_path": file_path,
-                    "checksum": checksum,
-                    "updated_at": datetime.fromtimestamp(file_stats.st_mtime).astimezone(),
-                },
-            )
-            status_code = 200
-        else:
-            # Create a new entity model
-            entity = EntityModel(
-                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).astimezone(),
-                updated_at=datetime.fromtimestamp(file_stats.st_mtime).astimezone(),
-            )
-            entity = await entity_repository.add(entity)
-            status_code = 201
-
-        # Index the file for search
-        await search_service.index_entity(entity)  # pyright: ignore
-
-        # Return success response
-        return JSONResponse(
-            status_code=status_code,
-            content={
-                "file_path": file_path,
-                "checksum": checksum,
-                "size": file_stats.st_size,
-                "created_at": file_stats.st_ctime,
-                "modified_at": file_stats.st_mtime,
-            },
-        )
-    except Exception as e:  # pragma: no cover
-        logger.error(f"Error writing resource {file_path}: {e}")
-        raise HTTPException(status_code=500, detail=f"Failed to write resource: {str(e)}")

src/basic_memory/api/routers/search_router.py

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

src/basic_memory/api/routers/utils.py

@@ -1,130 +0,0 @@
-from typing import Optional, List
-
-from basic_memory.repository import EntityRepository
-from basic_memory.repository.search_repository import SearchIndexRow
-from basic_memory.schemas.memory import (
-    EntitySummary,
-    ObservationSummary,
-    RelationSummary,
-    MemoryMetadata,
-    GraphContext,
-    ContextResult,
-)
-from basic_memory.schemas.search import SearchItemType, SearchResult
-from basic_memory.services import EntityService
-from basic_memory.services.context_service import (
-    ContextResultRow,
-    ContextResult as ServiceContextResult,
-)
-
-
-async def to_graph_context(
-    context_result: ServiceContextResult,
-    entity_repository: EntityRepository,
-    page: Optional[int] = None,
-    page_size: Optional[int] = None,
-):
-    # Helper function to convert items to summaries
-    async def to_summary(item: SearchIndexRow | ContextResultRow):
-        match item.type:
-            case SearchItemType.ENTITY:
-                return EntitySummary(
-                    title=item.title,  # pyright: ignore
-                    permalink=item.permalink,
-                    content=item.content,
-                    file_path=item.file_path,
-                    created_at=item.created_at,
-                )
-            case SearchItemType.OBSERVATION:
-                return ObservationSummary(
-                    title=item.title,  # pyright: ignore
-                    file_path=item.file_path,
-                    category=item.category,  # pyright: ignore
-                    content=item.content,  # pyright: ignore
-                    permalink=item.permalink,  # pyright: ignore
-                    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
-                return RelationSummary(
-                    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,
-                    created_at=item.created_at,
-                )
-            case _:  # pragma: no cover
-                raise ValueError(f"Unexpected type: {item.type}")
-
-    # Process the hierarchical results
-    hierarchical_results = []
-    for context_item in context_result.results:
-        # Process primary result
-        primary_result = await to_summary(context_item.primary_result)
-
-        # Process observations
-        observations = []
-        for obs in context_item.observations:
-            observations.append(await to_summary(obs))
-
-        # Process related results
-        related = []
-        for rel in context_item.related_results:
-            related.append(await to_summary(rel))
-
-        # Add to hierarchical results
-        hierarchical_results.append(
-            ContextResult(
-                primary_result=primary_result,
-                observations=observations,
-                related_results=related,
-            )
-        )
-
-    # Create schema metadata from service metadata
-    metadata = MemoryMetadata(
-        uri=context_result.metadata.uri,
-        types=context_result.metadata.types,
-        depth=context_result.metadata.depth,
-        timeframe=context_result.metadata.timeframe,
-        generated_at=context_result.metadata.generated_at,
-        primary_count=context_result.metadata.primary_count,
-        related_count=context_result.metadata.related_count,
-        total_results=context_result.metadata.primary_count + context_result.metadata.related_count,
-        total_relations=context_result.metadata.total_relations,
-        total_observations=context_result.metadata.total_observations,
-    )
-
-    # Return new GraphContext with just hierarchical results
-    return GraphContext(
-        results=hierarchical_results,
-        metadata=metadata,
-        page=page,
-        page_size=page_size,
-    )
-
-
-async def to_search_results(entity_service: EntityService, results: List[SearchIndexRow]):
-    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
-        search_results.append(
-            SearchResult(
-                title=r.title,  # pyright: ignore
-                type=r.type,  # pyright: ignore
-                permalink=r.permalink,
-                score=r.score,  # pyright: ignore
-                entity=entities[0].permalink if entities else None,
-                content=r.content,
-                file_path=r.file_path,
-                metadata=r.metadata,
-                category=r.category,
-                from_entity=entities[0].permalink if entities else None,
-                to_entity=entities[1].permalink if len(entities) > 1 else None,
-                relation_type=r.relation_type,
-            )
-        )
-    return search_results

src/basic_memory/api/template_loader.py

@@ -1,292 +0,0 @@
-"""Template loading and rendering utilities for the Basic Memory API.
-
-This module handles the loading and rendering of Handlebars templates from the
-templates directory, providing a consistent interface for all prompt-related
-formatting needs.
-"""
-
-import textwrap
-from typing import Dict, Any, Optional, Callable
-from pathlib import Path
-import json
-import datetime
-
-import pybars
-from loguru import logger
-
-# Get the base path of the templates directory
-TEMPLATES_DIR = Path(__file__).parent.parent / "templates"
-
-
-# Custom helpers for Handlebars
-def _date_helper(this, *args):
-    """Format a date using the given format string."""
-    if len(args) < 1:  # pragma: no cover
-        return ""
-
-    timestamp = args[0]
-    format_str = args[1] if len(args) > 1 else "%Y-%m-%d %H:%M"
-
-    if hasattr(timestamp, "strftime"):
-        result = timestamp.strftime(format_str)
-    elif isinstance(timestamp, str):
-        try:
-            dt = datetime.datetime.fromisoformat(timestamp)
-            result = dt.strftime(format_str)
-        except ValueError:
-            result = timestamp
-    else:
-        result = str(timestamp)  # pragma: no cover
-
-    return pybars.strlist([result])
-
-
-def _default_helper(this, *args):
-    """Return a default value if the given value is None or empty."""
-    if len(args) < 2:  # pragma: no cover
-        return ""
-
-    value = args[0]
-    default_value = args[1]
-
-    result = default_value if value is None or value == "" else value
-    # Use strlist for consistent handling of HTML escaping
-    return pybars.strlist([str(result)])
-
-
-def _capitalize_helper(this, *args):
-    """Capitalize the first letter of a string."""
-    if len(args) < 1:  # pragma: no cover
-        return ""
-
-    text = args[0]
-    if not text or not isinstance(text, str):  # pragma: no cover
-        result = ""
-    else:
-        result = text.capitalize()
-
-    return pybars.strlist([result])
-
-
-def _round_helper(this, *args):
-    """Round a number to the specified number of decimal places."""
-    if len(args) < 1:
-        return ""
-
-    value = args[0]
-    decimal_places = args[1] if len(args) > 1 else 2
-
-    try:
-        result = str(round(float(value), int(decimal_places)))
-    except (ValueError, TypeError):
-        result = str(value)
-
-    return pybars.strlist([result])
-
-
-def _size_helper(this, *args):
-    """Return the size/length of a collection."""
-    if len(args) < 1:
-        return 0
-
-    value = args[0]
-    if value is None:
-        result = "0"
-    elif isinstance(value, (list, tuple, dict, str)):
-        result = str(len(value))  # pragma: no cover
-    else:  # pragma: no cover
-        result = "0"
-
-    return pybars.strlist([result])
-
-
-def _json_helper(this, *args):
-    """Convert a value to a JSON string."""
-    if len(args) < 1:  # pragma: no cover
-        return "{}"
-
-    value = args[0]
-    # For pybars, we need to return a SafeString to prevent HTML escaping
-    result = json.dumps(value)  # pragma: no cover
-    # Safe string implementation to prevent HTML escaping
-    return pybars.strlist([result])
-
-
-def _math_helper(this, *args):
-    """Perform basic math operations."""
-    if len(args) < 3:
-        return pybars.strlist(["Math error: Insufficient arguments"])
-
-    lhs = args[0]
-    operator = args[1]
-    rhs = args[2]
-
-    try:
-        lhs = float(lhs)
-        rhs = float(rhs)
-        if operator == "+":
-            result = str(lhs + rhs)
-        elif operator == "-":
-            result = str(lhs - rhs)
-        elif operator == "*":
-            result = str(lhs * rhs)
-        elif operator == "/":
-            result = str(lhs / rhs)
-        else:
-            result = f"Unsupported operator: {operator}"
-    except (ValueError, TypeError) as e:
-        result = f"Math error: {e}"
-
-    return pybars.strlist([result])
-
-
-def _lt_helper(this, *args):
-    """Check if left hand side is less than right hand side."""
-    if len(args) < 2:
-        return False
-
-    lhs = args[0]
-    rhs = args[1]
-
-    try:
-        return float(lhs) < float(rhs)
-    except (ValueError, TypeError):
-        # Fall back to string comparison for non-numeric values
-        return str(lhs) < str(rhs)
-
-
-def _if_cond_helper(this, options, condition):
-    """Block helper for custom if conditionals."""
-    if condition:
-        return options["fn"](this)
-    elif "inverse" in options:
-        return options["inverse"](this)
-    return ""  # pragma: no cover
-
-
-def _dedent_helper(this, options):
-    """Dedent a block of text to remove common leading whitespace.
-
-    Usage:
-    {{#dedent}}
-        This text will have its
-        common leading whitespace removed
-        while preserving relative indentation.
-    {{/dedent}}
-    """
-    if "fn" not in options:  # pragma: no cover
-        return ""
-
-    # Get the content from the block
-    content = options["fn"](this)
-
-    # Convert to string if it's a strlist
-    if (
-        isinstance(content, list)
-        or hasattr(content, "__iter__")
-        and not isinstance(content, (str, bytes))
-    ):
-        content_str = "".join(str(item) for item in content)  # pragma: no cover
-    else:
-        content_str = str(content)  # pragma: no cover
-
-    # Add trailing and leading newlines to ensure proper dedenting
-    # This is critical for textwrap.dedent to work correctly with mixed content
-    content_str = "\n" + content_str + "\n"
-
-    # Use textwrap to dedent the content and remove the extra newlines we added
-    dedented = textwrap.dedent(content_str)[1:-1]
-
-    # Return as a SafeString to prevent HTML escaping
-    return pybars.strlist([dedented])  # pragma: no cover
-
-
-class TemplateLoader:
-    """Loader for Handlebars templates.
-
-    This class is responsible for loading templates from disk and rendering
-    them with the provided context data.
-    """
-
-    def __init__(self, template_dir: Optional[str] = None):
-        """Initialize the template loader.
-
-        Args:
-            template_dir: Optional custom template directory path
-        """
-        self.template_dir = Path(template_dir) if template_dir else TEMPLATES_DIR
-        self.template_cache: Dict[str, Callable] = {}
-        self.compiler = pybars.Compiler()
-
-        # Set up standard helpers
-        self.helpers = {
-            "date": _date_helper,
-            "default": _default_helper,
-            "capitalize": _capitalize_helper,
-            "round": _round_helper,
-            "size": _size_helper,
-            "json": _json_helper,
-            "math": _math_helper,
-            "lt": _lt_helper,
-            "if_cond": _if_cond_helper,
-            "dedent": _dedent_helper,
-        }
-
-        logger.debug(f"Initialized template loader with directory: {self.template_dir}")
-
-    def get_template(self, template_path: str) -> Callable:
-        """Get a template by path, using cache if available.
-
-        Args:
-            template_path: The path to the template, relative to the templates directory
-
-        Returns:
-            The compiled Handlebars template
-
-        Raises:
-            FileNotFoundError: If the template doesn't exist
-        """
-        if template_path in self.template_cache:
-            return self.template_cache[template_path]
-
-        # Convert from Liquid-style path to Handlebars extension
-        if template_path.endswith(".liquid"):
-            template_path = template_path.replace(".liquid", ".hbs")
-        elif not template_path.endswith(".hbs"):
-            template_path = f"{template_path}.hbs"
-
-        full_path = self.template_dir / template_path
-
-        if not full_path.exists():
-            raise FileNotFoundError(f"Template not found: {full_path}")
-
-        with open(full_path, "r", encoding="utf-8") as f:
-            template_str = f.read()
-
-        template = self.compiler.compile(template_str)
-        self.template_cache[template_path] = template
-
-        logger.debug(f"Loaded template: {template_path}")
-        return template
-
-    async def render(self, template_path: str, context: Dict[str, Any]) -> str:
-        """Render a template with the given context.
-
-        Args:
-            template_path: The path to the template, relative to the templates directory
-            context: The context data to pass to the template
-
-        Returns:
-            The rendered template as a string
-        """
-        template = self.get_template(template_path)
-        return template(context, helpers=self.helpers)
-
-    def clear_cache(self) -> None:
-        """Clear the template cache."""
-        self.template_cache.clear()
-        logger.debug("Template cache cleared")
-
-
-# Global template loader instance
-template_loader = TemplateLoader()

src/basic_memory/cli/__init__.py

@@ -1 +0,0 @@
-"""CLI tools for basic-memory"""

src/basic_memory/cli/app.py

@@ -1,54 +0,0 @@
-from typing import Optional
-
-import typer
-
-from basic_memory.config import ConfigManager
-
-
-def version_callback(value: bool) -> None:
-    """Show version and exit."""
-    if value:  # pragma: no cover
-        import basic_memory
-
-        typer.echo(f"Basic Memory version: {basic_memory.__version__}")
-        raise typer.Exit()
-
-
-app = typer.Typer(name="basic-memory")
-
-
-@app.callback()
-def app_callback(
-    ctx: typer.Context,
-    version: Optional[bool] = typer.Option(
-        None,
-        "--version",
-        "-v",
-        help="Show version and exit.",
-        callback=version_callback,
-        is_eager=True,
-    ),
-) -> 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.services.initialization import ensure_initialization
-
-        app_config = ConfigManager().config
-        ensure_initialization(app_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(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

@@ -1,277 +0,0 @@
-"""WorkOS OAuth Device Authorization for CLI."""
-
-import base64
-import hashlib
-import json
-import os
-import secrets
-import time
-import webbrowser
-
-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):
-        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
-
-    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 httpx.AsyncClient() 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 httpx.AsyncClient() 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 httpx.AsyncClient() 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,17 +0,0 @@
-"""CLI commands for basic-memory."""
-
-from . import status, sync, db, import_memory_json, mcp, import_claude_conversations
-from . import import_claude_projects, import_chatgpt, tool, project
-
-__all__ = [
-    "status",
-    "sync",
-    "db",
-    "import_memory_json",
-    "mcp",
-    "import_claude_conversations",
-    "import_claude_projects",
-    "import_chatgpt",
-    "tool",
-    "project",
-]

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

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

@@ -1,112 +0,0 @@
-"""Cloud API client utilities."""
-
-from typing import Optional
-
-import httpx
-import typer
-from rich.console import Console
-
-from basic_memory.cli.auth import CLIAuth
-from basic_memory.config import ConfigManager
-
-console = Console()
-
-
-class CloudAPIError(Exception):
-    """Exception raised for cloud API errors."""
-
-    def __init__(
-        self, message: str, status_code: Optional[int] = None, detail: Optional[dict] = None
-    ):
-        super().__init__(message)
-        self.status_code = status_code
-        self.detail = detail or {}
-
-
-class SubscriptionRequiredError(CloudAPIError):
-    """Exception raised when user needs an active subscription."""
-
-    def __init__(self, message: str, subscribe_url: str):
-        super().__init__(message, status_code=403, detail={"error": "subscription_required"})
-        self.subscribe_url = subscribe_url
-
-
-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() -> dict[str, str]:
-    """
-    Get authentication headers with JWT token.
-    handles jwt refresh if needed.
-    """
-    client_id, domain, _ = get_cloud_config()
-    auth = CLIAuth(client_id=client_id, authkit_domain=domain)
-    token = await auth.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}"}
-
-
-async def make_api_request(
-    method: str,
-    url: str,
-    headers: Optional[dict] = None,
-    json_data: Optional[dict] = None,
-    timeout: float = 30.0,
-) -> httpx.Response:
-    """Make an API request to the cloud service."""
-    headers = headers or {}
-    auth_headers = await get_authenticated_headers()
-    headers.update(auth_headers)
-    # Add debug headers to help with compression issues
-    headers.setdefault("Accept-Encoding", "identity")  # Disable compression for debugging
-
-    async with httpx.AsyncClient(timeout=timeout) 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

@@ -1,765 +0,0 @@
-"""Cloud bisync commands for Basic Memory CLI."""
-
-import asyncio
-import subprocess
-import time
-from datetime import datetime
-from pathlib import Path
-from typing import Optional
-
-import typer
-from rich.console import Console
-from rich.table import Table
-
-from basic_memory.cli.commands.cloud.api_client import CloudAPIError, make_api_request
-from basic_memory.cli.commands.cloud.cloud_utils import (
-    create_cloud_project,
-    fetch_cloud_projects,
-)
-from basic_memory.cli.commands.cloud.rclone_config import (
-    add_tenant_to_rclone_config,
-)
-from basic_memory.cli.commands.cloud.rclone_installer import RcloneInstallError, install_rclone
-from basic_memory.config import ConfigManager
-from basic_memory.ignore_utils import get_bmignore_path, create_default_bmignore
-from basic_memory.schemas.cloud import (
-    TenantMountInfo,
-    MountCredentials,
-)
-
-console = Console()
-
-
-class BisyncError(Exception):
-    """Exception raised for bisync-related errors."""
-
-    pass
-
-
-class RcloneBisyncProfile:
-    """Bisync profile with safety settings."""
-
-    def __init__(
-        self,
-        name: str,
-        conflict_resolve: str,
-        max_delete: int,
-        check_access: bool,
-        description: str,
-        extra_args: Optional[list[str]] = None,
-    ):
-        self.name = name
-        self.conflict_resolve = conflict_resolve
-        self.max_delete = max_delete
-        self.check_access = check_access
-        self.description = description
-        self.extra_args = extra_args or []
-
-
-# Bisync profiles based on SPEC-9 Phase 2.1
-BISYNC_PROFILES = {
-    "safe": RcloneBisyncProfile(
-        name="safe",
-        conflict_resolve="none",
-        max_delete=10,
-        check_access=False,
-        description="Safe mode with conflict preservation (keeps both versions)",
-    ),
-    "balanced": RcloneBisyncProfile(
-        name="balanced",
-        conflict_resolve="newer",
-        max_delete=25,
-        check_access=False,
-        description="Balanced mode - auto-resolve to newer file (recommended)",
-    ),
-    "fast": RcloneBisyncProfile(
-        name="fast",
-        conflict_resolve="newer",
-        max_delete=50,
-        check_access=False,
-        description="Fast mode for rapid iteration (skip verification)",
-    ),
-}
-
-
-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 scan_local_directories(sync_dir: Path) -> list[str]:
-    """Scan local sync directory for project folders.
-
-    Args:
-        sync_dir: Path to bisync directory
-
-    Returns:
-        List of directory names (project names)
-    """
-    if not sync_dir.exists():
-        return []
-
-    directories = []
-    for item in sync_dir.iterdir():
-        if item.is_dir() and not item.name.startswith("."):
-            directories.append(item.name)
-
-    return directories
-
-
-def get_bisync_state_path(tenant_id: str) -> Path:
-    """Get path to bisync state directory."""
-    return Path.home() / ".basic-memory" / "bisync-state" / tenant_id
-
-
-def get_bisync_directory() -> Path:
-    """Get bisync directory from config.
-
-    Returns:
-        Path to bisync directory (default: ~/basic-memory-cloud-sync)
-    """
-    config_manager = ConfigManager()
-    config = config_manager.config
-
-    sync_dir = config.bisync_config.get("sync_dir", str(Path.home() / "basic-memory-cloud-sync"))
-    return Path(sync_dir).expanduser().resolve()
-
-
-def validate_bisync_directory(bisync_dir: Path) -> None:
-    """Validate bisync directory doesn't conflict with mount.
-
-    Raises:
-        BisyncError: If bisync directory conflicts with mount directory
-    """
-    # Get fixed mount directory
-    mount_dir = (Path.home() / "basic-memory-cloud").resolve()
-
-    # Check if bisync dir is the same as mount dir
-    if bisync_dir == mount_dir:
-        raise BisyncError(
-            f"Cannot use {bisync_dir} for bisync - it's the mount directory!\n"
-            f"Mount and bisync must use different directories.\n\n"
-            f"Options:\n"
-            f"  1. Use default: ~/basic-memory-cloud-sync/\n"
-            f"  2. Specify different directory: --dir ~/my-sync-folder"
-        )
-
-    # Check if mount is active at this location
-    result = subprocess.run(["mount"], capture_output=True, text=True)
-    if str(bisync_dir) in result.stdout and "rclone" in result.stdout:
-        raise BisyncError(
-            f"{bisync_dir} is currently mounted via 'bm cloud mount'\n"
-            f"Cannot use mounted directory for bisync.\n\n"
-            f"Either:\n"
-            f"  1. Unmount first: bm cloud unmount\n"
-            f"  2. Use different directory for bisync"
-        )
-
-
-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()
-
-
-def bisync_state_exists(tenant_id: str) -> bool:
-    """Check if bisync state exists (has been initialized)."""
-    state_path = get_bisync_state_path(tenant_id)
-    return state_path.exists() and any(state_path.iterdir())
-
-
-def build_bisync_command(
-    tenant_id: str,
-    bucket_name: str,
-    local_path: Path,
-    profile: RcloneBisyncProfile,
-    dry_run: bool = False,
-    resync: bool = False,
-    verbose: bool = False,
-) -> list[str]:
-    """Build rclone bisync command with profile settings."""
-
-    # Sync with the entire bucket root (all projects)
-    rclone_remote = f"basic-memory-{tenant_id}:{bucket_name}"
-    filter_path = get_bisync_filter_path()
-    state_path = get_bisync_state_path(tenant_id)
-
-    # Ensure state directory exists
-    state_path.mkdir(parents=True, exist_ok=True)
-
-    cmd = [
-        "rclone",
-        "bisync",
-        str(local_path),
-        rclone_remote,
-        "--create-empty-src-dirs",
-        "--resilient",
-        f"--conflict-resolve={profile.conflict_resolve}",
-        f"--max-delete={profile.max_delete}",
-        "--filters-file",
-        str(filter_path),
-        "--workdir",
-        str(state_path),
-    ]
-
-    # Add verbosity flags
-    if verbose:
-        cmd.append("--verbose")  # Full details with file-by-file output
-    else:
-        # Show progress bar during transfers
-        cmd.append("--progress")
-
-    if profile.check_access:
-        cmd.append("--check-access")
-
-    if dry_run:
-        cmd.append("--dry-run")
-
-    if resync:
-        cmd.append("--resync")
-
-    cmd.extend(profile.extra_args)
-
-    return cmd
-
-
-def setup_cloud_bisync(sync_dir: Optional[str] = None) -> None:
-    """Set up cloud bisync with rclone installation and configuration.
-
-    Args:
-        sync_dir: Optional custom sync directory path. If not provided, uses config default.
-    """
-    console.print("[bold blue]Basic Memory Cloud Bisync Setup[/bold blue]")
-    console.print("Setting up bidirectional sync to your cloud tenant...\n")
-
-    try:
-        # Step 1: Install rclone
-        console.print("[blue]Step 1: Installing rclone...[/blue]")
-        install_rclone()
-
-        # Step 2: Get mount info (for tenant_id, bucket)
-        console.print("\n[blue]Step 2: Getting tenant information...[/blue]")
-        tenant_info = asyncio.run(get_mount_info())
-
-        tenant_id = tenant_info.tenant_id
-        bucket_name = tenant_info.bucket_name
-
-        console.print(f"[green]✓ Found tenant: {tenant_id}[/green]")
-        console.print(f"[green]✓ Bucket: {bucket_name}[/green]")
-
-        # Step 3: Generate credentials
-        console.print("\n[blue]Step 3: Generating sync credentials...[/blue]")
-        creds = asyncio.run(generate_mount_credentials(tenant_id))
-
-        access_key = creds.access_key
-        secret_key = creds.secret_key
-
-        console.print("[green]✓ Generated secure credentials[/green]")
-
-        # Step 4: Configure rclone
-        console.print("\n[blue]Step 4: Configuring rclone...[/blue]")
-        add_tenant_to_rclone_config(
-            tenant_id=tenant_id,
-            bucket_name=bucket_name,
-            access_key=access_key,
-            secret_key=secret_key,
-        )
-
-        # Step 5: Configure and create local directory
-        console.print("\n[blue]Step 5: Configuring sync directory...[/blue]")
-
-        # If custom sync_dir provided, save to config
-        if sync_dir:
-            config_manager = ConfigManager()
-            config = config_manager.load_config()
-            config.bisync_config["sync_dir"] = sync_dir
-            config_manager.save_config(config)
-            console.print("[green]✓ Saved custom sync directory to config[/green]")
-
-        # Get bisync directory (from config or default)
-        local_path = get_bisync_directory()
-
-        # Validate bisync directory
-        validate_bisync_directory(local_path)
-
-        # Create directory
-        local_path.mkdir(parents=True, exist_ok=True)
-        console.print(f"[green]✓ Created sync directory: {local_path}[/green]")
-
-        # Step 6: Perform initial resync
-        console.print("\n[blue]Step 6: Performing initial sync...[/blue]")
-        console.print("[yellow]This will establish the baseline for bidirectional sync.[/yellow]")
-
-        run_bisync(
-            tenant_id=tenant_id,
-            bucket_name=bucket_name,
-            local_path=local_path,
-            profile_name="balanced",
-            resync=True,
-        )
-
-        console.print("\n[bold green]✓ Bisync setup completed successfully![/bold green]")
-        console.print("\nYour local files will now sync bidirectionally with the cloud!")
-        console.print(f"\nLocal directory: {local_path}")
-        console.print("\nUseful commands:")
-        console.print("  bm sync                      # Run sync (recommended)")
-        console.print("  bm sync --watch              # Start watch mode")
-        console.print("  bm cloud status              # Check sync status")
-        console.print("  bm cloud check               # Verify file integrity")
-        console.print("  bm cloud bisync --dry-run    # Preview changes (advanced)")
-
-    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)
-
-
-def run_bisync(
-    tenant_id: Optional[str] = None,
-    bucket_name: Optional[str] = None,
-    local_path: Optional[Path] = None,
-    profile_name: str = "balanced",
-    dry_run: bool = False,
-    resync: bool = False,
-    verbose: bool = False,
-) -> bool:
-    """Run rclone bisync with specified profile."""
-
-    try:
-        # Get tenant info if not provided
-        if not tenant_id or not bucket_name:
-            tenant_info = asyncio.run(get_mount_info())
-            tenant_id = tenant_info.tenant_id
-            bucket_name = tenant_info.bucket_name
-
-        # Set default local path if not provided
-        if not local_path:
-            local_path = get_bisync_directory()
-
-        # Validate bisync directory
-        validate_bisync_directory(local_path)
-
-        # Check if local path exists
-        if not local_path.exists():
-            raise BisyncError(
-                f"Local directory {local_path} does not exist. Run 'basic-memory cloud bisync-setup' first."
-            )
-
-        # Get bisync profile
-        if profile_name not in BISYNC_PROFILES:
-            raise BisyncError(
-                f"Unknown profile: {profile_name}. Available: {list(BISYNC_PROFILES.keys())}"
-            )
-
-        profile = BISYNC_PROFILES[profile_name]
-
-        # Auto-register projects before sync (unless dry-run or resync)
-        if not dry_run and not resync:
-            try:
-                console.print("[dim]Checking for new projects...[/dim]")
-
-                # Fetch cloud projects and extract directory names from paths
-                cloud_data = asyncio.run(fetch_cloud_projects())
-                cloud_projects = cloud_data.projects
-
-                # Extract directory names from cloud project paths
-                # Compare directory names, not project names
-                # Cloud path /app/data/basic-memory -> directory name "basic-memory"
-                cloud_dir_names = set()
-                for p in cloud_projects:
-                    path = p.path
-                    # Strip /app/data/ prefix if present (cloud mode)
-                    if path.startswith("/app/data/"):
-                        path = path[len("/app/data/") :]
-                    # Get the last segment (directory name)
-                    dir_name = Path(path).name
-                    cloud_dir_names.add(dir_name)
-
-                # Scan local directories
-                local_dirs = scan_local_directories(local_path)
-
-                # Create missing cloud projects
-                new_projects = []
-                for dir_name in local_dirs:
-                    if dir_name not in cloud_dir_names:
-                        new_projects.append(dir_name)
-
-                if new_projects:
-                    console.print(
-                        f"[blue]Found {len(new_projects)} new local project(s), creating on cloud...[/blue]"
-                    )
-                    for project_name in new_projects:
-                        try:
-                            asyncio.run(create_cloud_project(project_name))
-                            console.print(f"[green]  ✓ Created project: {project_name}[/green]")
-                        except BisyncError as e:
-                            console.print(
-                                f"[yellow]  ⚠ Could not create {project_name}: {e}[/yellow]"
-                            )
-                else:
-                    console.print("[dim]All local projects already registered on cloud[/dim]")
-
-            except Exception as e:
-                console.print(f"[yellow]Warning: Project auto-registration failed: {e}[/yellow]")
-                console.print("[yellow]Continuing with sync anyway...[/yellow]")
-
-        # Check if first run and require resync
-        if not resync and not bisync_state_exists(tenant_id) and not dry_run:
-            raise BisyncError(
-                "First bisync requires --resync to establish baseline. "
-                "Run: basic-memory cloud bisync --resync"
-            )
-
-        # Build and execute bisync command
-        bisync_cmd = build_bisync_command(
-            tenant_id,
-            bucket_name,
-            local_path,
-            profile,
-            dry_run=dry_run,
-            resync=resync,
-            verbose=verbose,
-        )
-
-        if dry_run:
-            console.print("[yellow]DRY RUN MODE - No changes will be made[/yellow]")
-
-        console.print(
-            f"[blue]Running bisync with profile '{profile_name}' ({profile.description})...[/blue]"
-        )
-        console.print(f"[dim]Command: {' '.join(bisync_cmd)}[/dim]")
-        console.print()  # Blank line before output
-
-        # Stream output in real-time so user sees progress
-        result = subprocess.run(bisync_cmd, text=True)
-
-        if result.returncode != 0:
-            raise BisyncError(f"Bisync command failed with code {result.returncode}")
-
-        console.print()  # Blank line after output
-
-        if dry_run:
-            console.print("[green]✓ Dry run completed successfully[/green]")
-        elif resync:
-            console.print("[green]✓ Initial sync baseline established[/green]")
-        else:
-            console.print("[green]✓ Sync completed successfully[/green]")
-
-        # Notify container to refresh cache (if not dry run)
-        if not dry_run:
-            try:
-                asyncio.run(notify_container_sync(tenant_id))
-            except Exception as e:
-                console.print(f"[yellow]Warning: Could not notify container: {e}[/yellow]")
-
-        return True
-
-    except BisyncError:
-        raise
-    except Exception as e:
-        raise BisyncError(f"Unexpected error during bisync: {e}") from e
-
-
-async def notify_container_sync(tenant_id: str) -> None:
-    """Sync all projects after bisync completes."""
-    try:
-        from basic_memory.cli.commands.command_utils import run_sync
-
-        # Fetch all projects and sync each one
-        cloud_data = await fetch_cloud_projects()
-        projects = cloud_data.projects
-
-        if not projects:
-            console.print("[dim]No projects to sync[/dim]")
-            return
-
-        console.print(f"[blue]Notifying cloud to index {len(projects)} project(s)...[/blue]")
-
-        for project in projects:
-            project_name = project.name
-            if project_name:
-                try:
-                    await run_sync(project=project_name)
-                except Exception as e:
-                    # Non-critical, log and continue
-                    console.print(f"[yellow]  ⚠ Sync failed for {project_name}: {e}[/yellow]")
-
-        console.print("[dim]Note: Cloud indexing has started and may take a few moments[/dim]")
-
-    except Exception as e:
-        # Non-critical, don't fail the bisync
-        console.print(f"[yellow]Warning: Post-sync failed: {e}[/yellow]")
-
-
-def run_bisync_watch(
-    tenant_id: Optional[str] = None,
-    bucket_name: Optional[str] = None,
-    local_path: Optional[Path] = None,
-    profile_name: str = "balanced",
-    interval_seconds: int = 60,
-) -> None:
-    """Run bisync in watch mode with periodic syncs."""
-
-    console.print("[bold blue]Starting bisync watch mode[/bold blue]")
-    console.print(f"Sync interval: {interval_seconds} seconds")
-    console.print("Press Ctrl+C to stop\n")
-
-    try:
-        while True:
-            try:
-                start_time = time.time()
-
-                run_bisync(
-                    tenant_id=tenant_id,
-                    bucket_name=bucket_name,
-                    local_path=local_path,
-                    profile_name=profile_name,
-                )
-
-                elapsed = time.time() - start_time
-                console.print(f"[dim]Sync completed in {elapsed:.1f}s[/dim]")
-
-                # Wait for next interval
-                time.sleep(interval_seconds)
-
-            except BisyncError as e:
-                console.print(f"[red]Sync error: {e}[/red]")
-                console.print(f"[yellow]Retrying in {interval_seconds} seconds...[/yellow]")
-                time.sleep(interval_seconds)
-
-    except KeyboardInterrupt:
-        console.print("\n[yellow]Watch mode stopped[/yellow]")
-
-
-def show_bisync_status() -> None:
-    """Show current bisync status and configuration."""
-
-    try:
-        # Get tenant info
-        tenant_info = asyncio.run(get_mount_info())
-        tenant_id = tenant_info.tenant_id
-
-        local_path = get_bisync_directory()
-        state_path = get_bisync_state_path(tenant_id)
-
-        # Create status table
-        table = Table(title="Cloud Bisync Status", show_header=True, header_style="bold blue")
-        table.add_column("Property", style="green", min_width=20)
-        table.add_column("Value", style="dim", min_width=30)
-
-        # Check initialization status
-        is_initialized = bisync_state_exists(tenant_id)
-        init_status = (
-            "[green]✓ Initialized[/green]" if is_initialized else "[red]✗ Not initialized[/red]"
-        )
-
-        table.add_row("Tenant ID", tenant_id)
-        table.add_row("Local Directory", str(local_path))
-        table.add_row("Status", init_status)
-        table.add_row("State Directory", str(state_path))
-
-        # Check for last sync info
-        if is_initialized:
-            # Look for most recent state file
-            state_files = list(state_path.glob("*.lst"))
-            if state_files:
-                latest = max(state_files, key=lambda p: p.stat().st_mtime)
-                last_sync = datetime.fromtimestamp(latest.stat().st_mtime)
-                table.add_row("Last Sync", last_sync.strftime("%Y-%m-%d %H:%M:%S"))
-
-        console.print(table)
-
-        # Show bisync profiles
-        console.print("\n[bold]Available bisync profiles:[/bold]")
-        for name, profile in BISYNC_PROFILES.items():
-            console.print(f"  {name}: {profile.description}")
-            console.print(f"    - Conflict resolution: {profile.conflict_resolve}")
-            console.print(f"    - Max delete: {profile.max_delete} files")
-
-        console.print("\n[dim]To use a profile: bm cloud bisync --profile <name>[/dim]")
-
-        # Show setup instructions if not initialized
-        if not is_initialized:
-            console.print("\n[yellow]To initialize bisync, run:[/yellow]")
-            console.print("  bm cloud setup")
-            console.print("  or")
-            console.print("  bm cloud bisync --resync")
-
-    except Exception as e:
-        console.print(f"[red]Error getting bisync status: {e}[/red]")
-        raise typer.Exit(1)
-
-
-def run_check(
-    tenant_id: Optional[str] = None,
-    bucket_name: Optional[str] = None,
-    local_path: Optional[Path] = None,
-    one_way: bool = False,
-) -> bool:
-    """Check file integrity between local and cloud using rclone check.
-
-    Args:
-        tenant_id: Cloud tenant ID (auto-detected if not provided)
-        bucket_name: S3 bucket name (auto-detected if not provided)
-        local_path: Local bisync directory (uses config default if not provided)
-        one_way: If True, only check for missing files on destination (faster)
-
-    Returns:
-        True if check passed (files match), False if differences found
-    """
-    try:
-        # Check if rclone is installed
-        from basic_memory.cli.commands.cloud.rclone_installer import is_rclone_installed
-
-        if not is_rclone_installed():
-            raise BisyncError(
-                "rclone is not installed. Run 'bm cloud bisync-setup' first to set up cloud sync."
-            )
-
-        # Get tenant info if not provided
-        if not tenant_id or not bucket_name:
-            tenant_info = asyncio.run(get_mount_info())
-            tenant_id = tenant_id or tenant_info.tenant_id
-            bucket_name = bucket_name or tenant_info.bucket_name
-
-        # Get local path from config
-        if not local_path:
-            local_path = get_bisync_directory()
-
-        # Check if bisync is initialized
-        if not bisync_state_exists(tenant_id):
-            raise BisyncError(
-                "Bisync not initialized. Run 'bm cloud bisync --resync' to establish baseline."
-            )
-
-        # Build rclone check command
-        rclone_remote = f"basic-memory-{tenant_id}:{bucket_name}"
-        filter_path = get_bisync_filter_path()
-
-        cmd = [
-            "rclone",
-            "check",
-            str(local_path),
-            rclone_remote,
-            "--filter-from",
-            str(filter_path),
-        ]
-
-        if one_way:
-            cmd.append("--one-way")
-
-        console.print("[bold blue]Checking file integrity between local and cloud[/bold blue]")
-        console.print(f"[dim]Local:  {local_path}[/dim]")
-        console.print(f"[dim]Remote: {rclone_remote}[/dim]")
-        console.print(f"[dim]Command: {' '.join(cmd)}[/dim]")
-        console.print()
-
-        # Run check command
-        result = subprocess.run(cmd, capture_output=True, text=True)
-
-        # rclone check returns:
-        # 0 = success (all files match)
-        # non-zero = differences found or error
-        if result.returncode == 0:
-            console.print("[green]✓ All files match between local and cloud[/green]")
-            return True
-        else:
-            console.print("[yellow]⚠ Differences found:[/yellow]")
-            if result.stderr:
-                console.print(result.stderr)
-            if result.stdout:
-                console.print(result.stdout)
-            console.print("\n[dim]To sync differences, run: bm sync[/dim]")
-            return False
-
-    except BisyncError:
-        raise
-    except Exception as e:
-        raise BisyncError(f"Check failed: {e}") from e

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

@@ -1,100 +0,0 @@
-"""Shared utilities for cloud operations."""
-
-from basic_memory.cli.commands.cloud.api_client import make_api_request
-from basic_memory.config import ConfigManager
-from basic_memory.schemas.cloud import (
-    CloudProjectList,
-    CloudProjectCreateRequest,
-    CloudProjectCreateResponse,
-)
-from basic_memory.utils import generate_permalink
-
-
-class CloudUtilsError(Exception):
-    """Exception raised for cloud utility errors."""
-
-    pass
-
-
-async def fetch_cloud_projects() -> CloudProjectList:
-    """Fetch list of projects from cloud API.
-
-    Returns:
-        CloudProjectList with projects from cloud
-    """
-    try:
-        config_manager = ConfigManager()
-        config = config_manager.config
-        host_url = config.cloud_host.rstrip("/")
-
-        response = await make_api_request(method="GET", url=f"{host_url}/proxy/projects/projects")
-
-        return CloudProjectList.model_validate(response.json())
-    except Exception as e:
-        raise CloudUtilsError(f"Failed to fetch cloud projects: {e}") from e
-
-
-async def create_cloud_project(project_name: str) -> CloudProjectCreateResponse:
-    """Create a new project on cloud.
-
-    Args:
-        project_name: Name of project to create
-
-    Returns:
-        CloudProjectCreateResponse with project details from API
-    """
-    try:
-        config_manager = ConfigManager()
-        config = config_manager.config
-        host_url = config.cloud_host.rstrip("/")
-
-        # Use generate_permalink to ensure consistent naming
-        project_path = generate_permalink(project_name)
-
-        project_data = CloudProjectCreateRequest(
-            name=project_name,
-            path=project_path,
-            set_default=False,
-        )
-
-        response = await make_api_request(
-            method="POST",
-            url=f"{host_url}/proxy/projects/projects",
-            headers={"Content-Type": "application/json"},
-            json_data=project_data.model_dump(),
-        )
-
-        return CloudProjectCreateResponse.model_validate(response.json())
-    except Exception as e:
-        raise CloudUtilsError(f"Failed to create cloud project '{project_name}': {e}") from e
-
-
-async def sync_project(project_name: str) -> None:
-    """Trigger sync for a specific project on cloud.
-
-    Args:
-        project_name: Name of project to sync
-    """
-    try:
-        from basic_memory.cli.commands.command_utils import run_sync
-
-        await run_sync(project=project_name)
-    except Exception as e:
-        raise CloudUtilsError(f"Failed to sync project '{project_name}': {e}") from e
-
-
-async def project_exists(project_name: str) -> bool:
-    """Check if a project exists on cloud.
-
-    Args:
-        project_name: Name of project to check
-
-    Returns:
-        True if project exists, False otherwise
-    """
-    try:
-        projects = await fetch_cloud_projects()
-        project_names = {p.name for p in projects.projects}
-        return project_name in project_names
-    except Exception:
-        return False

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

@@ -1,288 +0,0 @@
-"""Core cloud commands for Basic Memory CLI."""
-
-import asyncio
-from typing import Optional
-
-import typer
-from rich.console import Console
-
-from basic_memory.cli.app import cloud_app
-from basic_memory.cli.auth import CLIAuth
-from basic_memory.config import ConfigManager
-from basic_memory.cli.commands.cloud.api_client import (
-    CloudAPIError,
-    SubscriptionRequiredError,
-    get_cloud_config,
-    make_api_request,
-)
-from basic_memory.cli.commands.cloud.mount_commands import (
-    mount_cloud_files,
-    setup_cloud_mount,
-    show_mount_status,
-    unmount_cloud_files,
-)
-from basic_memory.cli.commands.cloud.bisync_commands import (
-    run_bisync,
-    run_bisync_watch,
-    run_check,
-    setup_cloud_bisync,
-    show_bisync_status,
-)
-from basic_memory.cli.commands.cloud.rclone_config import MOUNT_PROFILES
-from basic_memory.cli.commands.cloud.bisync_commands import BISYNC_PROFILES
-
-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)
-
-    asyncio.run(_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(
-    bisync: bool = typer.Option(
-        True,
-        "--bisync/--mount",
-        help="Show bisync status (default) or mount status",
-    ),
-) -> None:
-    """Check cloud mode status and cloud instance health.
-
-    Shows cloud mode status, instance health, and sync/mount status.
-    Use --bisync (default) to show bisync status or --mount for mount status.
-    """
-    # 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 = asyncio.run(
-            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']}")
-
-        # Show sync/mount status based on flag
-        console.print()
-        if bisync:
-            show_bisync_status()
-        else:
-            show_mount_status()
-
-    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)
-
-
-# Mount commands
-
-
-@cloud_app.command("setup")
-def setup(
-    bisync: bool = typer.Option(
-        True,
-        "--bisync/--mount",
-        help="Use bidirectional sync (recommended) or mount as network drive",
-    ),
-    sync_dir: Optional[str] = typer.Option(
-        None,
-        "--dir",
-        help="Custom sync directory for bisync (default: ~/basic-memory-cloud-sync)",
-    ),
-) -> None:
-    """Set up cloud file access with automatic rclone installation and configuration.
-
-    Default: Sets up bidirectional sync (recommended).\n
-    Use --mount: Sets up mount as network drive (alternative workflow).\n
-
-    Examples:\n
-      bm cloud setup              # Setup bisync (default)\n
-      bm cloud setup --mount      # Setup mount instead\n
-      bm cloud setup --dir ~/sync # Custom bisync directory\n
-    """
-    if bisync:
-        setup_cloud_bisync(sync_dir=sync_dir)
-    else:
-        setup_cloud_mount()
-
-
-@cloud_app.command("mount")
-def mount(
-    profile: str = typer.Option(
-        "balanced", help=f"Mount profile: {', '.join(MOUNT_PROFILES.keys())}"
-    ),
-    path: Optional[str] = typer.Option(
-        None, help="Custom mount path (default: ~/basic-memory-{tenant-id})"
-    ),
-) -> None:
-    """Mount cloud files locally for editing."""
-    try:
-        mount_cloud_files(profile_name=profile)
-    except Exception as e:
-        console.print(f"[red]Mount failed: {e}[/red]")
-        raise typer.Exit(1)
-
-
-@cloud_app.command("unmount")
-def unmount() -> None:
-    """Unmount cloud files."""
-    try:
-        unmount_cloud_files()
-    except Exception as e:
-        console.print(f"[red]Unmount failed: {e}[/red]")
-        raise typer.Exit(1)
-
-
-# Bisync commands
-
-
-@cloud_app.command("bisync")
-def bisync(
-    profile: str = typer.Option(
-        "balanced", help=f"Bisync profile: {', '.join(BISYNC_PROFILES.keys())}"
-    ),
-    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without syncing"),
-    resync: bool = typer.Option(False, "--resync", help="Force resync to establish new baseline"),
-    watch: bool = typer.Option(False, "--watch", help="Run continuous sync in watch mode"),
-    interval: int = typer.Option(60, "--interval", help="Sync interval in seconds for watch mode"),
-    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed sync output"),
-) -> None:
-    """Run bidirectional sync between local files and cloud storage.
-
-    Examples:
-      basic-memory cloud bisync                    # Manual sync with balanced profile
-      basic-memory cloud bisync --dry-run          # Preview what would be synced
-      basic-memory cloud bisync --resync           # Establish new baseline
-      basic-memory cloud bisync --watch            # Continuous sync every 60s
-      basic-memory cloud bisync --watch --interval 30  # Continuous sync every 30s
-      basic-memory cloud bisync --profile safe     # Use safe profile (keep conflicts)
-      basic-memory cloud bisync --verbose          # Show detailed file sync output
-    """
-    try:
-        if watch:
-            run_bisync_watch(profile_name=profile, interval_seconds=interval)
-        else:
-            run_bisync(profile_name=profile, dry_run=dry_run, resync=resync, verbose=verbose)
-    except Exception as e:
-        console.print(f"[red]Bisync failed: {e}[/red]")
-        raise typer.Exit(1)
-
-
-@cloud_app.command("bisync-status")
-def bisync_status() -> None:
-    """Show current bisync status and configuration.
-
-    DEPRECATED: Use 'bm cloud status' instead (bisync is now the default).
-    """
-    console.print(
-        "[yellow]Note: 'bisync-status' is deprecated. Use 'bm cloud status' instead.[/yellow]"
-    )
-    console.print("[dim]Showing bisync status...[/dim]\n")
-    show_bisync_status()
-
-
-@cloud_app.command("check")
-def check(
-    one_way: bool = typer.Option(
-        False,
-        "--one-way",
-        help="Only check for missing files on destination (faster)",
-    ),
-) -> None:
-    """Check file integrity between local and cloud storage using rclone check.
-
-    Verifies that files match between your local bisync directory and cloud storage
-    without transferring any data. This is useful for validating sync integrity.
-
-    Examples:
-      bm cloud check              # Full integrity check
-      bm cloud check --one-way    # Faster check (missing files only)
-    """
-    try:
-        run_check(one_way=one_way)
-    except Exception as e:
-        console.print(f"[red]Check failed: {e}[/red]")
-        raise typer.Exit(1)

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

@@ -1,295 +0,0 @@
-"""Cloud mount commands for Basic Memory CLI."""
-
-import asyncio
-import subprocess
-import time
-from pathlib import Path
-from typing import Optional
-
-import typer
-from rich.console import Console
-from rich.table import Table
-
-from basic_memory.cli.commands.cloud.api_client import CloudAPIError, make_api_request
-from basic_memory.cli.commands.cloud.rclone_config import (
-    MOUNT_PROFILES,
-    add_tenant_to_rclone_config,
-    build_mount_command,
-    cleanup_orphaned_rclone_processes,
-    get_default_mount_path,
-    get_rclone_processes,
-    is_path_mounted,
-    unmount_path,
-)
-from basic_memory.cli.commands.cloud.rclone_installer import RcloneInstallError, install_rclone
-from basic_memory.config import ConfigManager
-
-console = Console()
-
-
-class MountError(Exception):
-    """Exception raised for mount-related errors."""
-
-    pass
-
-
-async def get_tenant_info() -> dict:
-    """Get current tenant information from cloud API."""
-    try:
-        config_manager = ConfigManager()
-        config = config_manager.config
-        host_url = config.cloud_host.rstrip("/")
-
-        response = await make_api_request(method="GET", url=f"{host_url}/tenant/mount/info")
-
-        return response.json()
-    except Exception as e:
-        raise MountError(f"Failed to get tenant info: {e}") from e
-
-
-async def generate_mount_credentials(tenant_id: str) -> dict:
-    """Generate scoped credentials for mounting."""
-    try:
-        config_manager = ConfigManager()
-        config = config_manager.config
-        host_url = config.cloud_host.rstrip("/")
-
-        response = await make_api_request(method="POST", url=f"{host_url}/tenant/mount/credentials")
-
-        return response.json()
-    except Exception as e:
-        raise MountError(f"Failed to generate mount credentials: {e}") from e
-
-
-def setup_cloud_mount() -> None:
-    """Set up cloud mount with rclone installation and configuration."""
-    console.print("[bold blue]Basic Memory Cloud Setup[/bold blue]")
-    console.print("Setting up local file access to your cloud tenant...\n")
-
-    try:
-        # Step 1: Install rclone
-        console.print("[blue]Step 1: Installing rclone...[/blue]")
-        install_rclone()
-
-        # Step 2: Get tenant info
-        console.print("\n[blue]Step 2: Getting tenant information...[/blue]")
-        tenant_info = asyncio.run(get_tenant_info())
-
-        tenant_id = tenant_info.get("tenant_id")
-        bucket_name = tenant_info.get("bucket_name")
-
-        if not tenant_id or not bucket_name:
-            raise MountError("Invalid tenant information received from cloud API")
-
-        console.print(f"[green]✓ Found tenant: {tenant_id}[/green]")
-        console.print(f"[green]✓ Bucket: {bucket_name}[/green]")
-
-        # Step 3: Generate mount credentials
-        console.print("\n[blue]Step 3: Generating mount credentials...[/blue]")
-        creds = asyncio.run(generate_mount_credentials(tenant_id))
-
-        access_key = creds.get("access_key")
-        secret_key = creds.get("secret_key")
-
-        if not access_key or not secret_key:
-            raise MountError("Failed to generate mount credentials")
-
-        console.print("[green]✓ Generated secure credentials[/green]")
-
-        # Step 4: Configure rclone
-        console.print("\n[blue]Step 4: Configuring rclone...[/blue]")
-        add_tenant_to_rclone_config(
-            tenant_id=tenant_id,
-            bucket_name=bucket_name,
-            access_key=access_key,
-            secret_key=secret_key,
-        )
-
-        # Step 5: Perform initial mount
-        console.print("\n[blue]Step 5: Mounting cloud files...[/blue]")
-        mount_path = get_default_mount_path()
-        MOUNT_PROFILES["balanced"]
-
-        mount_cloud_files(
-            tenant_id=tenant_id,
-            bucket_name=bucket_name,
-            mount_path=mount_path,
-            profile_name="balanced",
-        )
-
-        console.print("\n[bold green]✓ Cloud setup completed successfully![/bold green]")
-        console.print("\nYour cloud files are now accessible at:")
-        console.print(f"  {mount_path}")
-        console.print("\nYou can now edit files locally and they will sync to the cloud!")
-        console.print("\nUseful commands:")
-        console.print("  basic-memory cloud mount-status    # Check mount status")
-        console.print("  basic-memory cloud unmount         # Unmount files")
-        console.print("  basic-memory cloud mount --profile fast  # Remount with faster sync")
-
-    except (RcloneInstallError, MountError, CloudAPIError) as e:
-        console.print(f"\n[red]Setup failed: {e}[/red]")
-        raise typer.Exit(1)
-    except Exception as e:
-        console.print(f"\n[red]Unexpected error during setup: {e}[/red]")
-        raise typer.Exit(1)
-
-
-def mount_cloud_files(
-    tenant_id: Optional[str] = None,
-    bucket_name: Optional[str] = None,
-    mount_path: Optional[Path] = None,
-    profile_name: str = "balanced",
-) -> None:
-    """Mount cloud files with specified profile."""
-
-    try:
-        # Get tenant info if not provided
-        if not tenant_id or not bucket_name:
-            tenant_info = asyncio.run(get_tenant_info())
-            tenant_id = tenant_info.get("tenant_id")
-            bucket_name = tenant_info.get("bucket_name")
-
-            if not tenant_id or not bucket_name:
-                raise MountError("Could not determine tenant information")
-
-        # Set default mount path if not provided
-        if not mount_path:
-            mount_path = get_default_mount_path()
-
-        # Get mount profile
-        if profile_name not in MOUNT_PROFILES:
-            raise MountError(
-                f"Unknown profile: {profile_name}. Available: {list(MOUNT_PROFILES.keys())}"
-            )
-
-        profile = MOUNT_PROFILES[profile_name]
-
-        # Check if already mounted
-        if is_path_mounted(mount_path):
-            console.print(f"[yellow]Path {mount_path} is already mounted[/yellow]")
-            console.print("Use 'basic-memory cloud unmount' first, or mount to a different path")
-            return
-
-        # Create mount directory
-        mount_path.mkdir(parents=True, exist_ok=True)
-
-        # Build and execute mount command
-        mount_cmd = build_mount_command(tenant_id, bucket_name, mount_path, profile)
-
-        console.print(
-            f"[blue]Mounting with profile '{profile_name}' ({profile.description})...[/blue]"
-        )
-        console.print(f"[dim]Command: {' '.join(mount_cmd)}[/dim]")
-
-        result = subprocess.run(mount_cmd, capture_output=True, text=True)
-
-        if result.returncode != 0:
-            error_msg = result.stderr or "Unknown error"
-            raise MountError(f"Mount command failed: {error_msg}")
-
-        # Wait a moment for mount to establish
-        time.sleep(2)
-
-        # Verify mount
-        if is_path_mounted(mount_path):
-            console.print(f"[green]✓ Successfully mounted to {mount_path}[/green]")
-            console.print(f"[green]✓ Sync profile: {profile.description}[/green]")
-        else:
-            raise MountError("Mount command succeeded but path is not mounted")
-
-    except MountError:
-        raise
-    except Exception as e:
-        raise MountError(f"Unexpected error during mount: {e}") from e
-
-
-def unmount_cloud_files(tenant_id: Optional[str] = None) -> None:
-    """Unmount cloud files."""
-
-    try:
-        # Get tenant info if not provided
-        if not tenant_id:
-            tenant_info = asyncio.run(get_tenant_info())
-            tenant_id = tenant_info.get("tenant_id")
-
-            if not tenant_id:
-                raise MountError("Could not determine tenant ID")
-
-        mount_path = get_default_mount_path()
-
-        if not is_path_mounted(mount_path):
-            console.print(f"[yellow]Path {mount_path} is not mounted[/yellow]")
-            return
-
-        console.print(f"[blue]Unmounting {mount_path}...[/blue]")
-
-        # Unmount the path
-        if unmount_path(mount_path):
-            console.print(f"[green]✓ Successfully unmounted {mount_path}[/green]")
-
-            # Clean up any orphaned rclone processes
-            killed_count = cleanup_orphaned_rclone_processes()
-            if killed_count > 0:
-                console.print(
-                    f"[green]✓ Cleaned up {killed_count} orphaned rclone process(es)[/green]"
-                )
-        else:
-            console.print(f"[red]✗ Failed to unmount {mount_path}[/red]")
-            console.print("You may need to manually unmount or restart your system")
-
-    except MountError:
-        raise
-    except Exception as e:
-        raise MountError(f"Unexpected error during unmount: {e}") from e
-
-
-def show_mount_status() -> None:
-    """Show current mount status and running processes."""
-
-    try:
-        # Get tenant info
-        tenant_info = asyncio.run(get_tenant_info())
-        tenant_id = tenant_info.get("tenant_id")
-
-        if not tenant_id:
-            console.print("[red]Could not determine tenant ID[/red]")
-            return
-
-        mount_path = get_default_mount_path()
-
-        # Create status table
-        table = Table(title="Cloud Mount Status", show_header=True, header_style="bold blue")
-        table.add_column("Property", style="green", min_width=15)
-        table.add_column("Value", style="dim", min_width=30)
-
-        # Check mount status
-        is_mounted = is_path_mounted(mount_path)
-        mount_status = "[green]✓ Mounted[/green]" if is_mounted else "[red]✗ Not mounted[/red]"
-
-        table.add_row("Tenant ID", tenant_id)
-        table.add_row("Mount Path", str(mount_path))
-        table.add_row("Status", mount_status)
-
-        # Get rclone processes
-        processes = get_rclone_processes()
-        if processes:
-            table.add_row("rclone Processes", f"{len(processes)} running")
-        else:
-            table.add_row("rclone Processes", "None")
-
-        console.print(table)
-
-        # Show running processes details
-        if processes:
-            console.print("\n[bold]Running rclone processes:[/bold]")
-            for proc in processes:
-                console.print(f"  PID {proc['pid']}: {proc['command'][:80]}...")
-
-        # Show mount profiles
-        console.print("\n[bold]Available mount profiles:[/bold]")
-        for name, profile in MOUNT_PROFILES.items():
-            console.print(f"  {name}: {profile.description}")
-
-    except Exception as e:
-        console.print(f"[red]Error getting mount status: {e}[/red]")
-        raise typer.Exit(1)

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

@@ -1,288 +0,0 @@
-"""rclone configuration management for Basic Memory Cloud."""
-
-import configparser
-import os
-import shutil
-import subprocess
-from pathlib import Path
-from typing import Dict, List, Optional
-
-from rich.console import Console
-
-console = Console()
-
-
-class RcloneConfigError(Exception):
-    """Exception raised for rclone configuration errors."""
-
-    pass
-
-
-class RcloneMountProfile:
-    """Mount profile with optimized settings."""
-
-    def __init__(
-        self,
-        name: str,
-        cache_time: str,
-        poll_interval: str,
-        attr_timeout: str,
-        write_back: str,
-        description: str,
-        extra_args: Optional[List[str]] = None,
-    ):
-        self.name = name
-        self.cache_time = cache_time
-        self.poll_interval = poll_interval
-        self.attr_timeout = attr_timeout
-        self.write_back = write_back
-        self.description = description
-        self.extra_args = extra_args or []
-
-
-# Mount profiles based on SPEC-7 Phase 4 testing
-MOUNT_PROFILES = {
-    "fast": RcloneMountProfile(
-        name="fast",
-        cache_time="5s",
-        poll_interval="3s",
-        attr_timeout="3s",
-        write_back="1s",
-        description="Ultra-fast development (5s sync, higher bandwidth)",
-    ),
-    "balanced": RcloneMountProfile(
-        name="balanced",
-        cache_time="10s",
-        poll_interval="5s",
-        attr_timeout="5s",
-        write_back="2s",
-        description="Fast development (10-15s sync, recommended)",
-    ),
-    "safe": RcloneMountProfile(
-        name="safe",
-        cache_time="15s",
-        poll_interval="10s",
-        attr_timeout="10s",
-        write_back="5s",
-        description="Conflict-aware mount with backup",
-        extra_args=[
-            "--conflict-suffix",
-            ".conflict-{DateTimeExt}",
-            "--backup-dir",
-            "~/.basic-memory/conflicts",
-            "--track-renames",
-        ],
-    ),
-}
-
-
-def get_rclone_config_path() -> Path:
-    """Get the path to rclone configuration file."""
-    config_dir = Path.home() / ".config" / "rclone"
-    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 add_tenant_to_rclone_config(
-    tenant_id: str,
-    bucket_name: str,
-    access_key: str,
-    secret_key: str,
-    endpoint: str = "https://fly.storage.tigris.dev",
-    region: str = "auto",
-) -> str:
-    """Add tenant configuration to rclone config file."""
-
-    # Backup existing config
-    backup_rclone_config()
-
-    # Load existing config
-    config = load_rclone_config()
-
-    # Create section name
-    section_name = f"basic-memory-{tenant_id}"
-
-    # Add/update the tenant section
-    if not config.has_section(section_name):
-        config.add_section(section_name)
-
-    config.set(section_name, "type", "s3")
-    config.set(section_name, "provider", "Other")
-    config.set(section_name, "access_key_id", access_key)
-    config.set(section_name, "secret_access_key", secret_key)
-    config.set(section_name, "endpoint", endpoint)
-    config.set(section_name, "region", region)
-
-    # Save updated config
-    save_rclone_config(config)
-
-    console.print(f"[green]✓ Added tenant {tenant_id} to rclone config[/green]")
-    return section_name
-
-
-def remove_tenant_from_rclone_config(tenant_id: str) -> bool:
-    """Remove tenant configuration from rclone config."""
-    config = load_rclone_config()
-    section_name = f"basic-memory-{tenant_id}"
-
-    if config.has_section(section_name):
-        backup_rclone_config()
-        config.remove_section(section_name)
-        save_rclone_config(config)
-        console.print(f"[green]✓ Removed tenant {tenant_id} from rclone config[/green]")
-        return True
-
-    return False
-
-
-def get_default_mount_path() -> Path:
-    """Get default mount path (fixed location per SPEC-9).
-
-    Returns:
-        Fixed mount path: ~/basic-memory-cloud/
-    """
-    return Path.home() / "basic-memory-cloud"
-
-
-def build_mount_command(
-    tenant_id: str, bucket_name: str, mount_path: Path, profile: RcloneMountProfile
-) -> List[str]:
-    """Build rclone mount command with optimized settings."""
-
-    rclone_remote = f"basic-memory-{tenant_id}:{bucket_name}"
-
-    cmd = [
-        "rclone",
-        "nfsmount",
-        rclone_remote,
-        str(mount_path),
-        "--vfs-cache-mode",
-        "writes",
-        "--dir-cache-time",
-        profile.cache_time,
-        "--vfs-cache-poll-interval",
-        profile.poll_interval,
-        "--attr-timeout",
-        profile.attr_timeout,
-        "--vfs-write-back",
-        profile.write_back,
-        "--daemon",
-    ]
-
-    # Add profile-specific extra arguments
-    cmd.extend(profile.extra_args)
-
-    return cmd
-
-
-def is_path_mounted(mount_path: Path) -> bool:
-    """Check if a path is currently mounted."""
-    if not mount_path.exists():
-        return False
-
-    try:
-        # Check if mount point is actually mounted by looking for mount table entry
-        result = subprocess.run(["mount"], capture_output=True, text=True, check=False)
-
-        if result.returncode == 0:
-            # Look for our mount path in mount output
-            mount_str = str(mount_path.resolve())
-            return mount_str in result.stdout
-
-        return False
-    except Exception:
-        return False
-
-
-def get_rclone_processes() -> List[Dict[str, str]]:
-    """Get list of running rclone processes."""
-    try:
-        # Use ps to find rclone processes
-        result = subprocess.run(
-            ["ps", "-eo", "pid,args"], capture_output=True, text=True, check=False
-        )
-
-        processes = []
-        if result.returncode == 0:
-            for line in result.stdout.split("\n"):
-                if "rclone" in line and "basic-memory" in line:
-                    parts = line.strip().split(None, 1)
-                    if len(parts) >= 2:
-                        processes.append({"pid": parts[0], "command": parts[1]})
-
-        return processes
-    except Exception:
-        return []
-
-
-def kill_rclone_process(pid: str) -> bool:
-    """Kill a specific rclone process."""
-    try:
-        subprocess.run(["kill", pid], check=True)
-        console.print(f"[green]✓ Killed rclone process {pid}[/green]")
-        return True
-    except subprocess.CalledProcessError:
-        console.print(f"[red]✗ Failed to kill rclone process {pid}[/red]")
-        return False
-
-
-def unmount_path(mount_path: Path) -> bool:
-    """Unmount a mounted path."""
-    if not is_path_mounted(mount_path):
-        return True
-
-    try:
-        subprocess.run(["umount", str(mount_path)], check=True)
-        console.print(f"[green]✓ Unmounted {mount_path}[/green]")
-        return True
-    except subprocess.CalledProcessError as e:
-        console.print(f"[red]✗ Failed to unmount {mount_path}: {e}[/red]")
-        return False
-
-
-def cleanup_orphaned_rclone_processes() -> int:
-    """Clean up orphaned rclone processes for basic-memory."""
-    processes = get_rclone_processes()
-    killed_count = 0
-
-    for proc in processes:
-        console.print(
-            f"[yellow]Found rclone process: {proc['pid']} - {proc['command'][:80]}...[/yellow]"
-        )
-        if kill_rclone_process(proc["pid"]):
-            killed_count += 1
-
-    return killed_count

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

@@ -1,198 +0,0 @@
-"""Cross-platform rclone installation utilities."""
-
-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"])
-            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
-    raise RcloneInstallError(
-        "Could not install rclone automatically. Please install a package manager "
-        "(winget, chocolatey, or scoop) or install rclone manually from https://rclone.org/downloads/"
-    )
-
-
-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()
-        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 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

@@ -1,128 +0,0 @@
-"""WebDAV upload functionality for basic-memory projects."""
-
-import os
-from pathlib import Path
-
-import aiofiles
-import httpx
-
-from basic_memory.ignore_utils import load_gitignore_patterns, should_ignore_path
-from basic_memory.mcp.async_client import get_client
-from basic_memory.mcp.tools.utils import call_put
-
-
-async def upload_path(local_path: Path, project_name: str) -> 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)
-
-    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)]
-        else:
-            files_to_upload = _get_files_to_upload(local_path)
-
-        if not files_to_upload:
-            print("No files found to upload")
-            return True
-
-        print(f"Found {len(files_to_upload)} file(s) to upload")
-
-        # Upload files using httpx
-        total_bytes = 0
-
-        async with get_client() as client:
-            for i, (file_path, relative_path) in enumerate(files_to_upload, 1):
-                # 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)})")
-
-                # Read file content asynchronously
-                async with aiofiles.open(file_path, "rb") as f:
-                    content = await f.read()
-
-                # Upload via HTTP PUT to WebDAV endpoint
-                response = await call_put(client, remote_path, content=content)
-                response.raise_for_status()
-
-                total_bytes += file_path.stat().st_size
-
-        # Format 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"
-
-        print(f"✓ Upload complete: {len(files_to_upload)} file(s) ({size_str})")
-        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 _get_files_to_upload(directory: Path) -> list[tuple[Path, str]]:
-    """
-    Get list of files to upload from directory.
-
-    Uses .bmignore and .gitignore patterns for filtering.
-
-    Args:
-        directory: Directory to scan
-
-    Returns:
-        List of (absolute_path, relative_path) tuples
-    """
-    files = []
-
-    # Load ignore patterns from .bmignore and .gitignore
-    ignore_patterns = load_gitignore_patterns(directory)
-
-    # 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 not should_ignore_path(dir_path, directory, ignore_patterns):
-                filtered_dirs.append(d)
-        dirs[:] = filtered_dirs
-
-        # Process files
-        for filename in filenames:
-            file_path = root_path / filename
-
-            # Check if file should be ignored
-            if should_ignore_path(file_path, directory, ignore_patterns):
-                continue
-
-            # Calculate relative path for remote
-            rel_path = file_path.relative_to(directory)
-            # Use forward slashes for WebDAV paths
-            remote_path = str(rel_path).replace("\\", "/")
-
-            files.append((file_path, remote_path))
-
-    return files

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

@@ -1,93 +0,0 @@
-"""Upload CLI commands for basic-memory projects."""
-
-import asyncio
-from pathlib import Path
-
-import typer
-from rich.console import Console
-
-from basic_memory.cli.app import cloud_app
-from basic_memory.cli.commands.cloud.cloud_utils import (
-    create_cloud_project,
-    project_exists,
-    sync_project,
-)
-from basic_memory.cli.commands.cloud.upload import upload_path
-
-console = Console()
-
-
-@cloud_app.command("upload")
-def upload(
-    path: Path = typer.Argument(
-        ...,
-        help="Path to local file or directory to upload",
-        exists=True,
-        readable=True,
-        resolve_path=True,
-    ),
-    project: str = typer.Option(
-        ...,
-        "--project",
-        "-p",
-        help="Cloud project name (destination)",
-    ),
-    create_project: bool = typer.Option(
-        False,
-        "--create-project",
-        "-c",
-        help="Create project if it doesn't exist",
-    ),
-    sync: bool = typer.Option(
-        True,
-        "--sync/--no-sync",
-        help="Sync project after upload (default: true)",
-    ),
-) -> 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
-    """
-
-    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
-        console.print(f"[blue]Uploading {path} to project '{project}'...[/blue]")
-        success = await upload_path(path, project)
-        if not success:
-            console.print("[red]Upload failed[/red]")
-            raise typer.Exit(1)
-
-        console.print(f"[green]✅ Successfully uploaded to '{project}'[/green]")
-
-        # Sync project if requested
-        if sync:
-            console.print(f"[blue]Syncing project '{project}'...[/blue]")
-            try:
-                await sync_project(project)
-            except Exception as e:
-                console.print(f"[yellow]Warning: Sync failed: {e}[/yellow]")
-                console.print("[dim]Files uploaded but may not be indexed yet[/dim]")
-
-    asyncio.run(_upload())