basic-memory 0.7.0__py3-none-any.whl → 0.16.1__py3-none-any.whl

basic_memory/services/exceptions.py

@@ -14,3 +14,24 @@ class EntityCreationError(Exception):
     """Raised when an entity cannot be created"""
 
     pass
+
+
+class DirectoryOperationError(Exception):
+    """Raised when directory operations fail"""
+
+    pass
+
+
+class SyncFatalError(Exception):
+    """Raised when sync encounters a fatal error that prevents continuation.
+
+    Fatal errors include:
+    - Project deleted during sync (FOREIGN KEY constraint)
+    - Database corruption
+    - Critical system failures
+
+    When this exception is raised, the entire sync operation should be terminated
+    immediately rather than attempting to continue with remaining files.
+    """
+
+    pass

basic_memory/services/file_service.py

@@ -1,25 +1,35 @@
 """Service for file operations with checksum tracking."""
 
+import asyncio
+import hashlib
+import mimetypes
+from os import stat_result
 from pathlib import Path
-from typing import Tuple, Union
+from typing import Any, Dict, Tuple, Union
 
-from loguru import logger
+import aiofiles
+import yaml
 
 from basic_memory import file_utils
+from basic_memory.file_utils import FileError, ParseError
 from basic_memory.markdown.markdown_processor import MarkdownProcessor
 from basic_memory.models import Entity as EntityModel
 from basic_memory.schemas import Entity as EntitySchema
 from basic_memory.services.exceptions import FileOperationError
+from basic_memory.utils import FilePath
+from loguru import logger
 
 
 class FileService:
-    """Service for handling file operations.
+    """Service for handling file operations with concurrency control.
 
     All paths are handled as Path objects internally. Strings are converted to
     Path objects when passed in. Relative paths are assumed to be relative to
     base_path.
 
     Features:
+    - True async I/O with aiofiles (non-blocking)
+    - Built-in concurrency limits (semaphore)
     - Consistent file writing with checksums
     - Frontmatter management
     - Atomic operations
@@ -30,9 +40,13 @@ class FileService:
         self,
         base_path: Path,
         markdown_processor: MarkdownProcessor,
+        max_concurrent_files: int = 10,
     ):
         self.base_path = base_path.resolve()  # Get absolute path
         self.markdown_processor = markdown_processor
+        # Semaphore to limit concurrent file operations
+        # Prevents OOM on large projects by processing files in batches
+        self._file_semaphore = asyncio.Semaphore(max_concurrent_files)
 
     def get_entity_path(self, entity: Union[EntityModel, EntitySchema]) -> Path:
         """Generate absolute filesystem path for entity.
@@ -57,7 +71,7 @@ class FileService:
         Returns:
             Raw content string without metadata sections
         """
-        logger.debug(f"Reading entity with permalink: {entity.permalink}")
+        logger.debug(f"Reading entity content, entity_id={entity.id}, permalink={entity.permalink}")
 
         file_path = self.get_entity_path(entity)
         markdown = await self.markdown_processor.read_file(file_path)
@@ -75,13 +89,13 @@ class FileService:
         path = self.get_entity_path(entity)
         await self.delete_file(path)
 
-    async def exists(self, path: Union[Path, str]) -> bool:
+    async def exists(self, path: FilePath) -> bool:
         """Check if file exists at the provided path.
 
         If path is relative, it is assumed to be relative to base_path.
 
         Args:
-            path: Path to check (Path object or string)
+            path: Path to check (Path or string)
 
         Returns:
             True if file exists, False otherwise
@@ -90,23 +104,52 @@ class FileService:
             FileOperationError: If check fails
         """
         try:
-            path = Path(path)
-            if path.is_absolute():
-                return path.exists()
+            # Convert string to Path if needed
+            path_obj = self.base_path / path if isinstance(path, str) else path
+            logger.debug(f"Checking file existence: path={path_obj}")
+            if path_obj.is_absolute():
+                return path_obj.exists()
             else:
-                return (self.base_path / path).exists()
+                return (self.base_path / path_obj).exists()
         except Exception as e:
-            logger.error(f"Failed to check file existence {path}: {e}")
+            logger.error("Failed to check file existence", path=str(path), error=str(e))
             raise FileOperationError(f"Failed to check file existence: {e}")
 
-    async def write_file(self, path: Union[Path, str], content: str) -> str:
+    async def ensure_directory(self, path: FilePath) -> None:
+        """Ensure directory exists, creating if necessary.
+
+        Uses semaphore to control concurrency for directory creation operations.
+
+        Args:
+            path: Directory path to ensure (Path or string)
+
+        Raises:
+            FileOperationError: If directory creation fails
+        """
+        try:
+            # Convert string to Path if needed
+            path_obj = self.base_path / path if isinstance(path, str) else path
+            full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
+
+            # Use semaphore for concurrency control
+            async with self._file_semaphore:
+                # Run blocking mkdir in thread pool
+                loop = asyncio.get_event_loop()
+                await loop.run_in_executor(
+                    None, lambda: full_path.mkdir(parents=True, exist_ok=True)
+                )
+        except Exception as e:  # pragma: no cover
+            logger.error("Failed to create directory", path=str(path), error=str(e))
+            raise FileOperationError(f"Failed to create directory {path}: {e}")
+
+    async def write_file(self, path: FilePath, content: str) -> str:
         """Write content to file and return checksum.
 
         Handles both absolute and relative paths. Relative paths are resolved
         against base_path.
 
         Args:
-            path: Where to write (Path object or string)
+            path: Where to write (Path or string)
             content: Content to write
 
         Returns:
@@ -115,33 +158,78 @@ class FileService:
         Raises:
             FileOperationError: If write fails
         """
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        # Convert string to Path if needed
+        path_obj = self.base_path / path if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
 
         try:
             # Ensure parent directory exists
-            await file_utils.ensure_directory(full_path.parent)
+            await self.ensure_directory(full_path.parent)
 
             # Write content atomically
+            logger.info(
+                "Writing file: "
+                f"path={path_obj}, "
+                f"content_length={len(content)}, "
+                f"is_markdown={full_path.suffix.lower() == '.md'}"
+            )
+
             await file_utils.write_file_atomic(full_path, content)
 
             # Compute and return checksum
             checksum = await file_utils.compute_checksum(content)
-            logger.debug(f"wrote file: {full_path}, checksum: {checksum}")
+            logger.debug(f"File write completed path={full_path}, {checksum=}")
             return checksum
 
         except Exception as e:
-            logger.error(f"Failed to write file {full_path}: {e}")
+            logger.exception("File write error", path=str(full_path), error=str(e))
             raise FileOperationError(f"Failed to write file: {e}")
 
-    async def read_file(self, path: Union[Path, str]) -> Tuple[str, str]:
-        """Read file and compute checksum.
+    async def read_file_content(self, path: FilePath) -> str:
+        """Read file content using true async I/O with aiofiles.
 
         Handles both absolute and relative paths. Relative paths are resolved
         against base_path.
 
         Args:
-            path: Path to read (Path object or string)
+            path: Path to read (Path or string)
+
+        Returns:
+            File content as string
+
+        Raises:
+            FileOperationError: If read fails
+        """
+        # Convert string to Path if needed
+        path_obj = self.base_path / path if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
+
+        try:
+            logger.debug("Reading file content", operation="read_file_content", path=str(full_path))
+            async with aiofiles.open(full_path, mode="r", encoding="utf-8") as f:
+                content = await f.read()
+
+            logger.debug(
+                "File read completed",
+                path=str(full_path),
+                content_length=len(content),
+            )
+            return content
+
+        except Exception as e:
+            logger.exception("File read error", path=str(full_path), error=str(e))
+            raise FileOperationError(f"Failed to read file: {e}")
+
+    async def read_file(self, path: FilePath) -> Tuple[str, str]:
+        """Read file and compute checksum using true async I/O.
+
+        Uses aiofiles for non-blocking file reads.
+
+        Handles both absolute and relative paths. Relative paths are resolved
+        against base_path.
+
+        Args:
+            path: Path to read (Path or string)
 
         Returns:
             Tuple of (content, checksum)
@@ -149,28 +237,194 @@ class FileService:
         Raises:
             FileOperationError: If read fails
         """
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        # Convert string to Path if needed
+        path_obj = self.base_path / path if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
 
         try:
-            content = path.read_text()
+            logger.debug("Reading file", operation="read_file", path=str(full_path))
+
+            # Use aiofiles for non-blocking read
+            async with aiofiles.open(full_path, mode="r", encoding="utf-8") as f:
+                content = await f.read()
+
             checksum = await file_utils.compute_checksum(content)
-            logger.debug(f"read file: {full_path}, checksum: {checksum}")
+
+            logger.debug(
+                "File read completed",
+                path=str(full_path),
+                checksum=checksum,
+                content_length=len(content),
+            )
             return content, checksum
 
         except Exception as e:
-            logger.error(f"Failed to read file {full_path}: {e}")
+            logger.exception("File read error", path=str(full_path), error=str(e))
             raise FileOperationError(f"Failed to read file: {e}")
 
-    async def delete_file(self, path: Union[Path, str]) -> None:
+    async def delete_file(self, path: FilePath) -> None:
         """Delete file if it exists.
 
         Handles both absolute and relative paths. Relative paths are resolved
         against base_path.
 
         Args:
-            path: Path to delete (Path object or string)
+            path: Path to delete (Path or string)
         """
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        # Convert string to Path if needed
+        path_obj = self.base_path / path if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
         full_path.unlink(missing_ok=True)
+
+    async def update_frontmatter(self, path: FilePath, updates: Dict[str, Any]) -> str:
+        """Update frontmatter fields in a file while preserving all content.
+
+        Only modifies the frontmatter section, leaving all content untouched.
+        Creates frontmatter section if none exists.
+        Returns checksum of updated file.
+
+        Uses aiofiles for true async I/O (non-blocking).
+
+        Args:
+            path: Path to markdown file (Path or string)
+            updates: Dict of frontmatter fields to update
+
+        Returns:
+            Checksum of updated file
+
+        Raises:
+            FileOperationError: If file operations fail
+            ParseError: If frontmatter parsing fails
+        """
+        # Convert string to Path if needed
+        path_obj = self.base_path / path if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
+
+        try:
+            # Read current content using aiofiles
+            async with aiofiles.open(full_path, mode="r", encoding="utf-8") as f:
+                content = await f.read()
+
+            # Parse current frontmatter with proper error handling for malformed YAML
+            current_fm = {}
+            if file_utils.has_frontmatter(content):
+                try:
+                    current_fm = file_utils.parse_frontmatter(content)
+                    content = file_utils.remove_frontmatter(content)
+                except (ParseError, yaml.YAMLError) as e:
+                    # Log warning and treat as plain markdown without frontmatter
+                    logger.warning(
+                        f"Failed to parse YAML frontmatter in {full_path}: {e}. "
+                        "Treating file as plain markdown without frontmatter."
+                    )
+                    # Keep full content, treat as having no frontmatter
+                    current_fm = {}
+
+            # Update frontmatter
+            new_fm = {**current_fm, **updates}
+
+            # Write new file with updated frontmatter
+            yaml_fm = yaml.dump(new_fm, sort_keys=False, allow_unicode=True)
+            final_content = f"---\n{yaml_fm}---\n\n{content.strip()}"
+
+            logger.debug(
+                "Updating frontmatter", path=str(full_path), update_keys=list(updates.keys())
+            )
+
+            await file_utils.write_file_atomic(full_path, final_content)
+            return await file_utils.compute_checksum(final_content)
+
+        except Exception as e:
+            # Only log real errors (not YAML parsing, which is handled above)
+            if not isinstance(e, (ParseError, yaml.YAMLError)):
+                logger.error(
+                    "Failed to update frontmatter",
+                    path=str(full_path),
+                    error=str(e),
+                )
+            raise FileOperationError(f"Failed to update frontmatter: {e}")
+
+    async def compute_checksum(self, path: FilePath) -> str:
+        """Compute checksum for a file using true async I/O.
+
+        Uses aiofiles for non-blocking I/O with 64KB chunked reading.
+        Semaphore limits concurrent file operations to prevent OOM.
+        Memory usage is constant regardless of file size.
+
+        Args:
+            path: Path to the file (Path or string)
+
+        Returns:
+            SHA256 checksum hex string
+
+        Raises:
+            FileError: If checksum computation fails
+        """
+        # Convert string to Path if needed
+        path_obj = self.base_path / path if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
+
+        # Semaphore controls concurrency - max N files processed at once
+        async with self._file_semaphore:
+            try:
+                hasher = hashlib.sha256()
+                chunk_size = 65536  # 64KB chunks
+
+                # async I/O with aiofiles
+                async with aiofiles.open(full_path, mode="rb") as f:
+                    while chunk := await f.read(chunk_size):
+                        hasher.update(chunk)
+
+                return hasher.hexdigest()
+
+            except Exception as e:  # pragma: no cover
+                logger.error("Failed to compute checksum", path=str(full_path), error=str(e))
+                raise FileError(f"Failed to compute checksum for {path}: {e}")
+
+    def file_stats(self, path: FilePath) -> stat_result:
+        """Return file stats for a given path.
+
+        Args:
+            path: Path to the file (Path or string)
+
+        Returns:
+            File statistics
+        """
+        # Convert string to Path if needed
+        path_obj = self.base_path / path if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
+        # get file timestamps
+        return full_path.stat()
+
+    def content_type(self, path: FilePath) -> str:
+        """Return content_type for a given path.
+
+        Args:
+            path: Path to the file (Path or string)
+
+        Returns:
+            MIME type of the file
+        """
+        # Convert string to Path if needed
+        path_obj = self.base_path / path if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
+        # get file timestamps
+        mime_type, _ = mimetypes.guess_type(full_path.name)
+
+        # .canvas files are json
+        if full_path.suffix == ".canvas":
+            mime_type = "application/json"
+
+        content_type = mime_type or "text/plain"
+        return content_type
+
+    def is_markdown(self, path: FilePath) -> bool:
+        """Check if a file is a markdown file.
+
+        Args:
+            path: Path to the file (Path or string)
+
+        Returns:
+            True if the file is a markdown file, False otherwise
+        """
+        return self.content_type(path) == "text/markdown"

basic_memory/services/initialization.py

@@ -0,0 +1,191 @@
+"""Shared initialization service for Basic Memory.
+
+This module provides shared initialization functions used by both CLI and API
+to ensure consistent application startup across all entry points.
+"""
+
+import asyncio
+from pathlib import Path
+
+from loguru import logger
+
+from basic_memory import db
+from basic_memory.config import BasicMemoryConfig
+from basic_memory.models import Project
+from basic_memory.repository import (
+    ProjectRepository,
+)
+
+
+async def initialize_database(app_config: BasicMemoryConfig) -> None:
+    """Initialize database with migrations handled automatically by get_or_create_db.
+
+    Args:
+        app_config: The Basic Memory project configuration
+
+    Note:
+        Database migrations are now handled automatically when the database
+        connection is first established via get_or_create_db().
+    """
+    # Trigger database initialization and migrations by getting the database connection
+    try:
+        await db.get_or_create_db(app_config.database_path)
+        logger.info("Database initialization completed")
+    except Exception as e:
+        logger.error(f"Error initializing database: {e}")
+        # Allow application to continue - it might still work
+        # depending on what the error was, and will fail with a
+        # more specific error if the database is actually unusable
+
+
+async def reconcile_projects_with_config(app_config: BasicMemoryConfig):
+    """Ensure all projects in config.json exist in the projects table and vice versa.
+
+    This uses the ProjectService's synchronize_projects method to ensure bidirectional
+    synchronization between the configuration file and the database.
+
+    Args:
+        app_config: The Basic Memory application configuration
+    """
+    logger.info("Reconciling projects from config with database...")
+
+    # Get database session - migrations handled centrally
+    _, session_maker = await db.get_or_create_db(
+        db_path=app_config.database_path,
+        db_type=db.DatabaseType.FILESYSTEM,
+        ensure_migrations=False,
+    )
+    project_repository = ProjectRepository(session_maker)
+
+    # Import ProjectService here to avoid circular imports
+    from basic_memory.services.project_service import ProjectService
+
+    try:
+        # Create project service and synchronize projects
+        project_service = ProjectService(repository=project_repository)
+        await project_service.synchronize_projects()
+        logger.info("Projects successfully reconciled between config and database")
+    except Exception as e:
+        # Log the error but continue with initialization
+        logger.error(f"Error during project synchronization: {e}")
+        logger.info("Continuing with initialization despite synchronization error")
+
+
+async def initialize_file_sync(
+    app_config: BasicMemoryConfig,
+):
+    """Initialize file synchronization services. This function starts the watch service and does not return
+
+    Args:
+        app_config: The Basic Memory project configuration
+
+    Returns:
+        The watch service task that's monitoring file changes
+    """
+
+    # delay import
+    from basic_memory.sync import WatchService
+
+    # Load app configuration - migrations handled centrally
+    _, session_maker = await db.get_or_create_db(
+        db_path=app_config.database_path,
+        db_type=db.DatabaseType.FILESYSTEM,
+        ensure_migrations=False,
+    )
+    project_repository = ProjectRepository(session_maker)
+
+    # Initialize watch service
+    watch_service = WatchService(
+        app_config=app_config,
+        project_repository=project_repository,
+        quiet=True,
+    )
+
+    # Get active projects
+    active_projects = await project_repository.get_active_projects()
+
+    # Start sync for all projects as background tasks (non-blocking)
+    async def sync_project_background(project: Project):
+        """Sync a single project in the background."""
+        # avoid circular imports
+        from basic_memory.sync.sync_service import get_sync_service
+
+        logger.info(f"Starting background sync for project: {project.name}")
+        try:
+            # Create sync service
+            sync_service = await get_sync_service(project)
+
+            sync_dir = Path(project.path)
+            await sync_service.sync(sync_dir, project_name=project.name)
+            logger.info(f"Background sync completed successfully for project: {project.name}")
+        except Exception as e:  # pragma: no cover
+            logger.error(f"Error in background sync for project {project.name}: {e}")
+
+    # Create background tasks for all project syncs (non-blocking)
+    sync_tasks = [
+        asyncio.create_task(sync_project_background(project)) for project in active_projects
+    ]
+    logger.info(f"Created {len(sync_tasks)} background sync tasks")
+
+    # Don't await the tasks - let them run in background while we continue
+
+    # Then start the watch service in the background
+    logger.info("Starting watch service for all projects")
+    # run the watch service
+    try:
+        await watch_service.run()
+        logger.info("Watch service started")
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error starting watch service: {e}")
+
+    return None
+
+
+async def initialize_app(
+    app_config: BasicMemoryConfig,
+):
+    """Initialize the Basic Memory application.
+
+    This function handles all initialization steps:
+    - Running database migrations
+    - Reconciling projects from config.json with projects table
+    - Setting up file synchronization
+    - Starting background migration for legacy project data
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    logger.info("Initializing app...")
+    # Initialize database first
+    await initialize_database(app_config)
+
+    # Reconcile projects from config.json with projects table
+    await reconcile_projects_with_config(app_config)
+
+    logger.info("App initialization completed (migration running in background if needed)")
+
+
+def ensure_initialization(app_config: BasicMemoryConfig) -> None:
+    """Ensure initialization runs in a synchronous context.
+
+    This is a wrapper for the async initialize_app function that can be
+    called from synchronous code like CLI entry points.
+
+    No-op if app_config.cloud_mode == True. Cloud basic memory manages it's own projects
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    # Skip initialization in cloud mode - cloud manages its own projects
+    if app_config.cloud_mode_enabled:
+        logger.debug("Skipping initialization in cloud mode - projects managed by cloud")
+        return
+
+    try:
+        result = asyncio.run(initialize_app(app_config))
+        logger.info(f"Initialization completed successfully: result={result}")
+    except Exception as e:  # pragma: no cover
+        logger.exception(f"Error during initialization: {e}")
+        # Continue execution even if initialization fails
+        # The command might still work, or will fail with a
+        # more specific error message