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

basic_memory/project_resolver.py

@@ -0,0 +1,222 @@
+"""Unified project resolution across MCP, API, and CLI.
+
+This module provides a single canonical implementation of project resolution
+logic, eliminating duplicated decision trees across the codebase.
+
+The resolution follows a three-tier hierarchy:
+1. Constrained mode: BASIC_MEMORY_MCP_PROJECT env var (highest priority)
+2. Explicit parameter: Project passed directly to operation
+3. Default project: Used when default_project_mode=true (lowest priority)
+
+In cloud mode, project is required unless discovery mode is explicitly allowed.
+"""
+
+import os
+from dataclasses import dataclass
+from enum import Enum, auto
+from typing import Optional
+
+from loguru import logger
+
+
+class ResolutionMode(Enum):
+    """How the project was resolved."""
+
+    CLOUD_EXPLICIT = auto()  # Explicit project in cloud mode
+    CLOUD_DISCOVERY = auto()  # Discovery mode allowed in cloud (no project)
+    ENV_CONSTRAINT = auto()  # BASIC_MEMORY_MCP_PROJECT env var
+    EXPLICIT = auto()  # Explicit project parameter
+    DEFAULT = auto()  # default_project with default_project_mode=true
+    NONE = auto()  # No resolution possible
+
+
+@dataclass(frozen=True)
+class ResolvedProject:
+    """Result of project resolution.
+
+    Attributes:
+        project: The resolved project name, or None if not resolved
+        mode: How the project was resolved
+        reason: Human-readable explanation of resolution
+    """
+
+    project: Optional[str]
+    mode: ResolutionMode
+    reason: str
+
+    @property
+    def is_resolved(self) -> bool:
+        """Whether a project was successfully resolved."""
+        return self.project is not None
+
+    @property
+    def is_discovery_mode(self) -> bool:
+        """Whether we're in discovery mode (no specific project)."""
+        return self.mode == ResolutionMode.CLOUD_DISCOVERY or (
+            self.mode == ResolutionMode.NONE and self.project is None
+        )
+
+
+@dataclass
+class ProjectResolver:
+    """Unified project resolution logic.
+
+    Resolves the effective project given requested project, environment
+    constraints, and configuration settings.
+
+    This is the single canonical implementation of project resolution,
+    used by MCP tools, API routes, and CLI commands.
+
+    Args:
+        cloud_mode: Whether running in cloud mode (project required)
+        default_project_mode: Whether to use default project when not specified
+        default_project: The default project name
+        constrained_project: Optional env-constrained project override
+            (typically from BASIC_MEMORY_MCP_PROJECT)
+    """
+
+    cloud_mode: bool = False
+    default_project_mode: bool = False
+    default_project: Optional[str] = None
+    constrained_project: Optional[str] = None
+
+    @classmethod
+    def from_env(
+        cls,
+        cloud_mode: bool = False,
+        default_project_mode: bool = False,
+        default_project: Optional[str] = None,
+    ) -> "ProjectResolver":
+        """Create resolver with constrained_project from environment.
+
+        Args:
+            cloud_mode: Whether running in cloud mode
+            default_project_mode: Whether to use default project when not specified
+            default_project: The default project name
+
+        Returns:
+            ProjectResolver configured with current environment
+        """
+        constrained = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+        return cls(
+            cloud_mode=cloud_mode,
+            default_project_mode=default_project_mode,
+            default_project=default_project,
+            constrained_project=constrained,
+        )
+
+    def resolve(
+        self,
+        project: Optional[str] = None,
+        allow_discovery: bool = False,
+    ) -> ResolvedProject:
+        """Resolve project using the three-tier hierarchy.
+
+        Resolution order:
+        1. Cloud mode check (project required unless discovery allowed)
+        2. Constrained project from env var (highest priority in local mode)
+        3. Explicit project parameter
+        4. Default project if default_project_mode=true
+
+        Args:
+            project: Optional explicit project parameter
+            allow_discovery: If True, allows returning None in cloud mode
+                for discovery operations (e.g., recent_activity across projects)
+
+        Returns:
+            ResolvedProject with project name, resolution mode, and reason
+
+        Raises:
+            ValueError: If in cloud mode and no project specified (unless discovery allowed)
+        """
+        # --- Cloud Mode Handling ---
+        # In cloud mode, project is required unless discovery is explicitly allowed
+        if self.cloud_mode:
+            if project:
+                logger.debug(f"Cloud mode: using explicit project '{project}'")
+                return ResolvedProject(
+                    project=project,
+                    mode=ResolutionMode.CLOUD_EXPLICIT,
+                    reason=f"Explicit project in cloud mode: {project}",
+                )
+            elif allow_discovery:
+                logger.debug("Cloud mode: discovery mode allowed, no project required")
+                return ResolvedProject(
+                    project=None,
+                    mode=ResolutionMode.CLOUD_DISCOVERY,
+                    reason="Discovery mode enabled in cloud",
+                )
+            else:
+                raise ValueError("No project specified. Project is required for cloud mode.")
+
+        # --- Local Mode: Three-Tier Hierarchy ---
+
+        # Priority 1: CLI constraint overrides everything
+        if self.constrained_project:
+            logger.debug(f"Using CLI constrained project: {self.constrained_project}")
+            return ResolvedProject(
+                project=self.constrained_project,
+                mode=ResolutionMode.ENV_CONSTRAINT,
+                reason=f"Environment constraint: BASIC_MEMORY_MCP_PROJECT={self.constrained_project}",
+            )
+
+        # Priority 2: Explicit project parameter
+        if project:
+            logger.debug(f"Using explicit project parameter: {project}")
+            return ResolvedProject(
+                project=project,
+                mode=ResolutionMode.EXPLICIT,
+                reason=f"Explicit parameter: {project}",
+            )
+
+        # Priority 3: Default project mode
+        if self.default_project_mode and self.default_project:
+            logger.debug(f"Using default project from config: {self.default_project}")
+            return ResolvedProject(
+                project=self.default_project,
+                mode=ResolutionMode.DEFAULT,
+                reason=f"Default project mode: {self.default_project}",
+            )
+
+        # No resolution possible
+        logger.debug("No project resolution possible")
+        return ResolvedProject(
+            project=None,
+            mode=ResolutionMode.NONE,
+            reason="No project specified and default_project_mode is disabled",
+        )
+
+    def require_project(
+        self,
+        project: Optional[str] = None,
+        error_message: Optional[str] = None,
+    ) -> ResolvedProject:
+        """Resolve project, raising an error if not resolved.
+
+        Convenience method for operations that require a project.
+
+        Args:
+            project: Optional explicit project parameter
+            error_message: Custom error message if project not resolved
+
+        Returns:
+            ResolvedProject (always with a non-None project)
+
+        Raises:
+            ValueError: If project could not be resolved
+        """
+        result = self.resolve(project, allow_discovery=False)
+        if not result.is_resolved:
+            msg = error_message or (
+                "No project specified. Either set 'default_project_mode=true' in config, "
+                "or provide a 'project' argument."
+            )
+            raise ValueError(msg)
+        return result
+
+
+__all__ = [
+    "ProjectResolver",
+    "ResolvedProject",
+    "ResolutionMode",
+]

basic_memory/repository/entity_repository.py

@@ -1,7 +1,8 @@
 """Repository for managing entities in the knowledge graph."""
 
 from pathlib import Path
-from typing import List, Optional, Sequence, Union
+from typing import List, Optional, Sequence, Union, Any
+
 
 from loguru import logger
 from sqlalchemy import select
@@ -9,6 +10,7 @@ from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 from sqlalchemy.orm import selectinload
 from sqlalchemy.orm.interfaces import LoaderOption
+from sqlalchemy.engine import Row
 
 from basic_memory import db
 from basic_memory.models.knowledge import Entity, Observation, Relation
@@ -31,6 +33,34 @@ class EntityRepository(Repository[Entity]):
         """
         super().__init__(session_maker, Entity, project_id=project_id)
 
+    async def get_by_id(self, entity_id: int) -> Optional[Entity]:  # pragma: no cover
+        """Get entity by numeric ID.
+
+        Args:
+            entity_id: Numeric entity ID
+
+        Returns:
+            Entity if found, None otherwise
+        """
+        async with db.scoped_session(self.session_maker) as session:
+            return await self.select_by_id(session, entity_id)
+
+    async def get_by_external_id(self, external_id: str) -> Optional[Entity]:
+        """Get entity by external UUID.
+
+        Args:
+            external_id: External UUID identifier
+
+        Returns:
+            Entity if found, None otherwise
+        """
+        query = (
+            self.select()
+            .where(Entity.external_id == external_id)
+            .options(*self.get_load_options())
+        )
+        return await self.find_one(query)
+
     async def get_by_permalink(self, permalink: str) -> Optional[Entity]:
         """Get entity by permalink.
 
@@ -63,6 +93,129 @@ class EntityRepository(Repository[Entity]):
         )
         return await self.find_one(query)
 
+    # -------------------------------------------------------------------------
+    # Lightweight methods for permalink resolution (no eager loading)
+    # -------------------------------------------------------------------------
+
+    async def permalink_exists(self, permalink: str) -> bool:
+        """Check if a permalink exists without loading the full entity.
+
+        This is much faster than get_by_permalink() as it skips eager loading
+        of observations and relations. Use for existence checks in bulk operations.
+
+        Args:
+            permalink: Permalink to check
+
+        Returns:
+            True if permalink exists, False otherwise
+        """
+        query = select(Entity.id).where(Entity.permalink == permalink).limit(1)
+        query = self._add_project_filter(query)
+        result = await self.execute_query(query, use_query_options=False)
+        return result.scalar_one_or_none() is not None
+
+    async def get_file_path_for_permalink(self, permalink: str) -> Optional[str]:
+        """Get the file_path for a permalink without loading the full entity.
+
+        Use when you only need the file_path, not the full entity with relations.
+
+        Args:
+            permalink: Permalink to look up
+
+        Returns:
+            file_path string if found, None otherwise
+        """
+        query = select(Entity.file_path).where(Entity.permalink == permalink)
+        query = self._add_project_filter(query)
+        result = await self.execute_query(query, use_query_options=False)
+        return result.scalar_one_or_none()
+
+    async def get_permalink_for_file_path(self, file_path: Union[Path, str]) -> Optional[str]:
+        """Get the permalink for a file_path without loading the full entity.
+
+        Use when you only need the permalink, not the full entity with relations.
+
+        Args:
+            file_path: File path to look up
+
+        Returns:
+            permalink string if found, None otherwise
+        """
+        query = select(Entity.permalink).where(Entity.file_path == Path(file_path).as_posix())
+        query = self._add_project_filter(query)
+        result = await self.execute_query(query, use_query_options=False)
+        return result.scalar_one_or_none()
+
+    async def get_all_permalinks(self) -> List[str]:
+        """Get all permalinks for this project.
+
+        Optimized for bulk operations - returns only permalink strings
+        without loading entities or relationships.
+
+        Returns:
+            List of all permalinks in the project
+        """
+        query = select(Entity.permalink)
+        query = self._add_project_filter(query)
+        result = await self.execute_query(query, use_query_options=False)
+        return list(result.scalars().all())
+
+    async def get_permalink_to_file_path_map(self) -> dict[str, str]:
+        """Get a mapping of permalink -> file_path for all entities.
+
+        Optimized for bulk permalink resolution - loads minimal data in one query.
+
+        Returns:
+            Dict mapping permalink to file_path
+        """
+        query = select(Entity.permalink, Entity.file_path)
+        query = self._add_project_filter(query)
+        result = await self.execute_query(query, use_query_options=False)
+        return {row.permalink: row.file_path for row in result.all()}
+
+    async def get_file_path_to_permalink_map(self) -> dict[str, str]:
+        """Get a mapping of file_path -> permalink for all entities.
+
+        Optimized for bulk permalink resolution - loads minimal data in one query.
+
+        Returns:
+            Dict mapping file_path to permalink
+        """
+        query = select(Entity.file_path, Entity.permalink)
+        query = self._add_project_filter(query)
+        result = await self.execute_query(query, use_query_options=False)
+        return {row.file_path: row.permalink for row in result.all()}
+
+    async def get_by_file_paths(
+        self, session: AsyncSession, file_paths: Sequence[Union[Path, str]]
+    ) -> List[Row[Any]]:
+        """Get file paths and checksums for multiple entities (optimized for change detection).
+
+        Only queries file_path and checksum columns, skips loading full entities and relationships.
+        This is much faster than loading complete Entity objects when you only need checksums.
+
+        Args:
+            session: Database session to use for the query
+            file_paths: List of file paths to query
+
+        Returns:
+            List of (file_path, checksum) tuples for matching entities
+        """
+        if not file_paths:  # pragma: no cover
+            return []  # pragma: no cover
+
+        # Convert all paths to POSIX strings for consistent comparison
+        posix_paths = [Path(fp).as_posix() for fp in file_paths]  # pragma: no cover
+
+        # Query ONLY file_path and checksum columns (not full Entity objects)
+        query = select(Entity.file_path, Entity.checksum).where(  # pragma: no cover
+            Entity.file_path.in_(posix_paths)
+        )
+        query = self._add_project_filter(query)  # pragma: no cover
+
+        result = await session.execute(query)  # pragma: no cover
+        return list(result.all())  # pragma: no cover
+
     async def find_by_checksum(self, checksum: str) -> Sequence[Entity]:
         """Find entities with the given checksum.
 
@@ -80,6 +233,34 @@ class EntityRepository(Repository[Entity]):
         result = await self.execute_query(query, use_query_options=False)
         return list(result.scalars().all())
 
+    async def find_by_checksums(self, checksums: Sequence[str]) -> Sequence[Entity]:
+        """Find entities with any of the given checksums (batch query for move detection).
+
+        This is a batch-optimized version of find_by_checksum() that queries multiple checksums
+        in a single database query. Used for efficient move detection in cloud indexing.
+
+        Performance: For 1000 new files, this makes 1 query vs 1000 individual queries (~100x faster).
+
+        Example:
+            When processing new files, we check if any are actually moved files by finding
+            entities with matching checksums at different paths.
+
+        Args:
+            checksums: List of file content checksums to search for
+
+        Returns:
+            Sequence of entities with matching checksums (may be empty).
+            Multiple entities may have the same checksum if files were copied.
+        """
+        if not checksums:  # pragma: no cover
+            return []  # pragma: no cover
+
+        # Query: SELECT * FROM entities WHERE checksum IN (checksum1, checksum2, ...)
+        query = self.select().where(Entity.checksum.in_(checksums))  # pragma: no cover
+        # Don't load relationships for move detection - we only need file_path and checksum
+        result = await self.execute_query(query, use_query_options=False)  # pragma: no cover
+        return list(result.scalars().all())  # pragma: no cover
+
     async def delete_by_file_path(self, file_path: Union[Path, str]) -> bool:
         """Delete entity with the provided file_path.
 
@@ -155,8 +336,13 @@ class EntityRepository(Repository[Entity]):
 
             except IntegrityError as e:
                 # Check if this is a FOREIGN KEY constraint failure
+                # SQLite: "FOREIGN KEY constraint failed"
+                # Postgres: "violates foreign key constraint"
                 error_str = str(e)
-                if "FOREIGN KEY constraint failed" in error_str:
+                if (
+                    "FOREIGN KEY constraint failed" in error_str
+                    or "violates foreign key constraint" in error_str
+                ):
                     # Import locally to avoid circular dependency (repository -> services -> repository)
                     from basic_memory.services.exceptions import SyncFatalError
 
@@ -310,5 +496,26 @@ class EntityRepository(Repository[Entity]):
 
         # Insert with unique permalink
         session.add(entity)
-        await session.flush()
+        try:
+            await session.flush()
+        except IntegrityError as e:  # pragma: no cover
+            # Check if this is a FOREIGN KEY constraint failure
+            # SQLite: "FOREIGN KEY constraint failed"
+            # Postgres: "violates foreign key constraint"
+            error_str = str(e)
+            if (
+                "FOREIGN KEY constraint failed" in error_str
+                or "violates foreign key constraint" in error_str
+            ):
+                # Import locally to avoid circular dependency (repository -> services -> repository)
+                from basic_memory.services.exceptions import SyncFatalError
+
+                # Project doesn't exist in database - this is a fatal sync error
+                raise SyncFatalError(  # pragma: no cover
+                    f"Cannot sync file '{entity.file_path}': "
+                    f"project_id={entity.project_id} does not exist in database. "
+                    f"The project may have been deleted. This sync will be terminated."
+                ) from e
+            # Re-raise if not a foreign key error
+            raise  # pragma: no cover
         return entity

basic_memory/repository/observation_repository.py

@@ -2,6 +2,7 @@
 
 from typing import Dict, List, Sequence
 
+
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import async_sessionmaker