basic-memory 0.15.0__tar.gz → 0.15.1__tar.gz

{basic_memory-0.15.0 → basic_memory-0.15.1}/.github/workflows/test.yml

@@ -60,10 +60,6 @@ jobs:
         run: |
           just typecheck
 
-      - name: Run type checks
-        run: |
-          just typecheck
-
       - name: Run linting
         run: |
           just lint

{basic_memory-0.15.0 → basic_memory-0.15.1}/CHANGELOG.md

@@ -1,5 +1,160 @@
 # CHANGELOG
 
+## v0.15.1 (2025-10-13)
+
+### Performance Improvements
+
+- **#352**: Optimize sync/indexing for 43% faster performance
+  ([`c0538ad`](https://github.com/basicmachines-co/basic-memory/commit/c0538ad2perf0d68a2a3604e255c3f2c42c5ed))
+  - Significant performance improvements to file synchronization and indexing operations
+  - 43% reduction in sync time for large knowledge bases
+  - Optimized database queries and file processing
+
+- **#350**: Optimize directory operations for 10-100x performance improvement
+  ([`00b73b0`](https://github.com/basicmachines-co/basic-memory/commit/00b73b0d))
+  - Dramatic performance improvements for directory listing operations
+  - 10-100x faster directory traversal depending on knowledge base size
+  - Reduced memory footprint for large directory structures
+  - Exclude null fields from directory endpoint responses for smaller payloads
+
+### Bug Fixes
+
+- **#355**: Update view_note and ChatGPT tools for Claude Desktop compatibility
+  ([`2b7008d`](https://github.com/basicmachines-co/basic-memory/commit/2b7008d9))
+  - Fix view_note tool formatting for better Claude Desktop rendering
+  - Update ChatGPT tool integration for improved compatibility
+  - Enhanced artifact display in Claude Desktop interface
+
+- **#348**: Add permalink normalization to project lookups in deps.py
+  ([`a09066e`](https://github.com/basicmachines-co/basic-memory/commit/a09066e0))
+  - Fix project lookup failures due to case sensitivity
+  - Normalize permalinks consistently across project operations
+  - Improve project switching reliability
+
+- **#345**: Project deletion failing with permalink normalization
+  ([`be352ab`](https://github.com/basicmachines-co/basic-memory/commit/be352ab4))
+  - Fix project deletion errors related to permalink handling
+  - Ensure proper cleanup of project resources
+  - Improve error messages for deletion failures
+
+- **#341**: Correct ProjectItem.home property to return path instead of name
+  ([`3e876a7`](https://github.com/basicmachines-co/basic-memory/commit/3e876a75))
+  - Fix ProjectItem.home to return correct project path
+  - Resolve configuration issues with project paths
+  - Improve project path resolution consistency
+
+- **#339**: Prevent nested project paths to avoid data conflicts
+  ([`795e339`](https://github.com/basicmachines-co/basic-memory/commit/795e3393))
+  - Block creation of nested project paths that could cause data conflicts
+  - Add validation to prevent project path hierarchy issues
+  - Improve error messages for invalid project configurations
+
+- **#338**: Normalize paths to lowercase in cloud mode to prevent case collisions
+  ([`07e304c`](https://github.com/basicmachines-co/basic-memory/commit/07e304ce))
+  - Fix path case sensitivity issues in cloud deployments
+  - Normalize paths consistently across cloud operations
+  - Prevent data loss from case-insensitive filesystem collisions
+
+- **#336**: Cloud mode path validation and sanitization (bmc-issue-103)
+  ([`2a1c06d`](https://github.com/basicmachines-co/basic-memory/commit/2a1c06d9))
+  - Enhanced path validation for cloud deployments
+  - Improved path sanitization to prevent security issues
+  - Better error handling for invalid paths in cloud mode
+
+- **#332**: Cloud mode path validation and sanitization
+  ([`7616b2b`](https://github.com/basicmachines-co/basic-memory/commit/7616b2bb))
+  - Additional cloud mode path fixes and improvements
+  - Comprehensive path validation for cloud environments
+  - Security enhancements for path handling
+
+### Features
+
+- **#344**: Async client context manager pattern for cloud consolidation (SPEC-16)
+  ([`8d2e70c`](https://github.com/basicmachines-co/basic-memory/commit/8d2e70cf))
+  - Refactor async client to use context manager pattern
+  - Improve resource management and cleanup
+  - Enable better dependency injection for cloud deployments
+  - Foundation for cloud platform consolidation
+
+- **#343**: Add SPEC-15 for configuration persistence via Tigris
+  ([`53438d1`](https://github.com/basicmachines-co/basic-memory/commit/53438d1e))
+  - Design specification for persistent configuration storage
+  - Foundation for cloud configuration management
+  - Tigris S3-compatible storage integration planning
+
+- **#334**: Introduce BASIC_MEMORY_PROJECT_ROOT for path constraints
+  ([`ccc4386`](https://github.com/basicmachines-co/basic-memory/commit/ccc43866))
+  - Add environment variable for constraining project paths
+  - Improve security by limiting project creation locations
+  - Better control over project directory structure
+
+### Documentation
+
+- **#335**: v0.15.0 assistant guide updates
+  ([`c6f93a0`](https://github.com/basicmachines-co/basic-memory/commit/c6f93a02))
+  - Update AI assistant guide for v0.15.0 features
+  - Improve documentation for new MCP tools
+  - Better examples and usage patterns
+
+- **#339**: Add tool use documentation to write_note for root folder usage
+  ([`73202d1`](https://github.com/basicmachines-co/basic-memory/commit/73202d1a))
+  - Document how to use empty string for root folder in write_note
+  - Clarify folder parameter usage
+  - Improve tool documentation clarity
+
+- Fix link in ai_assistant_guide resource
+  ([`2a1c06d`](https://github.com/basicmachines-co/basic-memory/commit/2a1c06d9))
+  - Correct broken documentation links
+  - Improve resource accessibility
+
+### Refactoring
+
+- Add SPEC-17 and SPEC-18 documentation
+  ([`962d88e`](https://github.com/basicmachines-co/basic-memory/commit/962d88ea))
+  - New specification documents for future features
+  - Architecture planning and design documentation
+
+### Breaking Changes
+
+**None** - This release maintains full backward compatibility with v0.15.0
+
+### Migration Guide
+
+No manual migration required. Upgrade with:
+
+```bash
+# Update via uv
+uv tool upgrade basic-memory
+
+# Or install fresh
+uv tool install basic-memory
+```
+
+**What's Fixed:**
+- Significant performance improvements (43% faster sync, 10-100x faster directory operations)
+- Multiple cloud deployment stability fixes
+- Project path validation and normalization issues resolved
+- Better Claude Desktop and ChatGPT integration
+
+**What's New:**
+- Context manager pattern for async clients (foundation for cloud consolidation)
+- BASIC_MEMORY_PROJECT_ROOT environment variable for path constraints
+- Enhanced cloud mode path handling and security
+- SPEC-15 and SPEC-16 architecture documentation
+
+### Installation
+
+```bash
+# Latest stable release
+uv tool install basic-memory
+
+# Update existing installation
+uv tool upgrade basic-memory
+
+# Docker
+docker pull ghcr.io/basicmachines-co/basic-memory:v0.15.1
+```
+
 ## v0.15.0 (2025-10-04)
 
 ### Critical Bug Fixes

{basic_memory-0.15.0 → basic_memory-0.15.1}/CLAUDE.md

@@ -14,20 +14,34 @@ See the [README.md](README.md) file for a project overview.
 
 ### Build and Test Commands
 
-- Install: `make install` or `pip install -e ".[dev]"`
-- Run tests: `uv run pytest -p pytest_mock -v` or `make test`
+- 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`
-- Lint: `make lint` or `ruff check . --fix`
-- Type check: `make type-check` or `uv run pyright`
-- Format: `make format` or `uv run ruff format .`
-- Run all code checks: `make check` (runs lint, format, type-check, test)
-- Create db migration: `make migration m="Your migration message"`
-- Run development MCP Inspector: `make run-inspector`
+- 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
+- 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
@@ -61,9 +75,46 @@ See the [README.md](README.md) file for a project overview.
 - Schema changes require Alembic migrations
 - SQLite is used for indexing and full text search, files are source of truth
 - Testing uses pytest with asyncio support (strict mode)
+- Unit tests (`tests/`) use mocks when necessary; integration tests (`test-int/`) use real implementations
 - Test database uses in-memory SQLite
-- Avoid creating mocks in tests in most circumstances.
-- Each test runs in a standalone environment with in memory SQLite and tmp_file directory
+- 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
 
@@ -80,6 +131,7 @@ See the [README.md](README.md) file for a project overview.
 
 ### 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`
@@ -89,24 +141,41 @@ See the [README.md](README.md) file for a project overview.
     - 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_file(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
+    - `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")
+    - `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(query, page, page_size)` - Full-text search across all content with filtering options
+    - `search_notes(query, page, page_size, search_type, types, entity_types, after_date)` - Full-text search across all content with advanced filtering options
+
+  **Project Management:**
+    - `list_memory_projects()` - List all available projects with their status
+    - `create_memory_project(project_name, project_path, set_default)` - Create new Basic Memory projects
+    - `delete_project(project_name)` - Delete a project from configuration
+    - `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
@@ -118,6 +187,34 @@ See the [README.md](README.md) file for a project overview.
     - `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
@@ -168,4 +265,4 @@ With GitHub integration, the development workflow includes:
 3. **Branch management** - Claude can create feature branches for implementations
 4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
 
-This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.
+This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.

{basic_memory-0.15.0 → basic_memory-0.15.1}/CONTRIBUTING.md

@@ -34,11 +34,18 @@ project and how to get started as a developer.
 
 4. **Run the Tests**:
    ```bash
-   # Run all tests
+   # Run all tests with unified coverage (unit + integration)
    just test
-   # or
-   uv run pytest -p pytest_mock -v
-   
+
+   # Run unit tests only (fast, no coverage)
+   just test-unit
+
+   # Run integration tests only (fast, no coverage)
+   just test-int
+
+   # Generate HTML coverage report
+   just coverage
+
    # Run a specific test
    pytest tests/path/to/test_file.py::test_function_name
    ```
@@ -134,7 +141,7 @@ agreement to the DCO.
 
 ## Code Style Guidelines
 
-- **Python Version**: Python 3.12+ with full type annotations
+- **Python Version**: Python 3.12+ with full type annotations (3.12+ required for type parameter syntax)
 - **Line Length**: 100 characters maximum
 - **Formatting**: Use ruff for consistent styling
 - **Import Order**: Standard lib, third-party, local imports
@@ -144,12 +151,78 @@ agreement to the DCO.
 
 ## Testing Guidelines
 
-- **Coverage Target**: We aim for 100% test coverage for all code
+### Test Structure
+
+Basic Memory uses two test directories with unified coverage reporting:
+
+- **`tests/`**: Unit tests that test individual components in isolation
+  - Fast execution with extensive mocking
+  - Test individual functions, classes, and modules
+  - Run with: `just test-unit` (no coverage, fast)
+
+- **`test-int/`**: Integration tests that test real-world scenarios
+  - Test full workflows with real database and file operations
+  - Include performance benchmarks
+  - More realistic but slower than unit tests
+  - Run with: `just test-int` (no coverage, fast)
+
+### Running Tests
+
+```bash
+# Run all tests with unified coverage report
+just test
+
+# Run only unit tests (fast iteration)
+just test-unit
+
+# Run only integration tests
+just test-int
+
+# Generate HTML coverage report
+just coverage
+
+# Run specific test
+pytest tests/path/to/test_file.py::test_function_name
+
+# Run tests excluding benchmarks
+pytest -m "not benchmark"
+
+# Run only benchmark tests
+pytest -m benchmark test-int/test_sync_performance_benchmark.py
+```
+
+### Performance Benchmarks
+
+The `test-int/test_sync_performance_benchmark.py` file contains performance benchmarks that measure sync and indexing speed:
+
+- `test_benchmark_sync_100_files` - Small repository performance
+- `test_benchmark_sync_500_files` - Medium repository performance
+- `test_benchmark_sync_1000_files` - Large repository performance (marked slow)
+- `test_benchmark_resync_no_changes` - Re-sync performance baseline
+
+Run benchmarks with:
+```bash
+# Run all benchmarks (excluding slow ones)
+pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"
+
+# Run all benchmarks including slow ones
+pytest test-int/test_sync_performance_benchmark.py -v -m benchmark
+
+# Run specific benchmark
+pytest test-int/test_sync_performance_benchmark.py::test_benchmark_sync_100_files -v
+```
+
+See `test-int/BENCHMARKS.md` for detailed benchmark documentation.
+
+### Testing Best Practices
+
+- **Coverage Target**: We aim for high test coverage for all code
 - **Test Framework**: Use pytest for unit and integration tests
-- **Mocking**: Use pytest-mock for mocking dependencies only when necessary
+- **Mocking**: Avoid mocking in integration tests; use sparingly in unit tests
 - **Edge Cases**: Test both normal operation and edge cases
 - **Database Testing**: Use in-memory SQLite for testing database operations
 - **Fixtures**: Use async pytest fixtures for setup and teardown
+- **Markers**: Use `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests
 
 ## Release Process
 

{basic_memory-0.15.0 → basic_memory-0.15.1}/Dockerfile

@@ -24,11 +24,12 @@ WORKDIR /app
 RUN uv sync --locked
 
 # Create necessary directories and set ownership
-RUN mkdir -p /app/data /app/.basic-memory && \
+RUN mkdir -p /app/data/basic-memory /app/.basic-memory && \
     chown -R appuser:${GID} /app
 
 # Set default data directory and add venv to PATH
-ENV BASIC_MEMORY_HOME=/app/data \
+ENV BASIC_MEMORY_HOME=/app/data/basic-memory \
+    BASIC_MEMORY_PROJECT_ROOT=/app/data \
     PATH="/app/.venv/bin:$PATH"
 
 # Switch to the non-root user

{basic_memory-0.15.0 → basic_memory-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basic-memory
-Version: 0.15.0
+Version: 0.15.1
 Summary: Local-first knowledge management combining Zettelkasten with knowledge graphs
 Project-URL: Homepage, https://github.com/basicmachines-co/basic-memory
 Project-URL: Repository, https://github.com/basicmachines-co/basic-memory
@@ -8,7 +8,7 @@ Project-URL: Documentation, https://github.com/basicmachines-co/basic-memory#rea
 Author-email: Basic Machines <hello@basic-machines.co>
 License: AGPL-3.0-or-later
 License-File: LICENSE
-Requires-Python: >=3.12.1
+Requires-Python: >=3.12
 Requires-Dist: aiofiles>=24.1.0
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: alembic>=1.14.1
@@ -139,6 +139,9 @@ With Basic Memory, you can:
 - Keep everything local and under your control
 - Use familiar tools like Obsidian to view and edit notes
 - Build a personal knowledge base that grows over time
+- Sync your knowledge to the cloud with bidirectional synchronization
+- Authenticate and manage cloud projects with subscription validation
+- Mount cloud storage for direct file access
 
 ## How It Works in Practice
 
@@ -385,14 +388,57 @@ basic-memory sync
 basic-memory sync --watch
 ```
 
-3. In Claude Desktop, the LLM can now use these tools:
+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
-search(query, page, page_size) - Search across your knowledge base
 recent_activity(type, depth, timeframe) - Find recently updated information
+list_directory(dir_name, depth) - Browse directory contents with filtering
+```
+
+**Search & Discovery:**
+```
+search(query, page, page_size) - Search across your knowledge base
+```
+
+**Project Management:**
+```
+list_memory_projects() - List all available projects
+create_memory_project(project_name, project_path) - Create new projects
+get_current_project() - Show current project stats
+sync_status() - Check synchronization status
+```
+
+**Visualization:**
+```
 canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 ```
 
@@ -412,6 +458,7 @@ See the [Documentation](https://memory.basicmachines.co/) for more info, includi
 
 - [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)
 

{basic_memory-0.15.0 → basic_memory-0.15.1}/README.md

@@ -100,6 +100,9 @@ With Basic Memory, you can:
 - Keep everything local and under your control
 - Use familiar tools like Obsidian to view and edit notes
 - Build a personal knowledge base that grows over time
+- Sync your knowledge to the cloud with bidirectional synchronization
+- Authenticate and manage cloud projects with subscription validation
+- Mount cloud storage for direct file access
 
 ## How It Works in Practice
 
@@ -346,14 +349,57 @@ basic-memory sync
 basic-memory sync --watch
 ```
 
-3. In Claude Desktop, the LLM can now use these tools:
+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
-search(query, page, page_size) - Search across your knowledge base
 recent_activity(type, depth, timeframe) - Find recently updated information
+list_directory(dir_name, depth) - Browse directory contents with filtering
+```
+
+**Search & Discovery:**
+```
+search(query, page, page_size) - Search across your knowledge base
+```
+
+**Project Management:**
+```
+list_memory_projects() - List all available projects
+create_memory_project(project_name, project_path) - Create new projects
+get_current_project() - Show current project stats
+sync_status() - Check synchronization status
+```
+
+**Visualization:**
+```
 canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 ```
 
@@ -373,6 +419,7 @@ See the [Documentation](https://memory.basicmachines.co/) for more info, includi
 
 - [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)