basic-memory 0.14.4__py3-none-any.whl → 0.15.1__py3-none-any.whl

basic_memory/repository/search_repository.py

@@ -62,7 +62,7 @@ class SearchIndexRow:
 
         # Normalize path separators to handle both Windows (\) and Unix (/) paths
         normalized_path = Path(self.file_path).as_posix()
-        
+
         # Split the path by slashes
         parts = normalized_path.split("/")
 
@@ -527,7 +527,9 @@ class SearchRepository:
         async with db.scoped_session(self.session_maker) as session:
             # Delete existing record if any
             await session.execute(
-                text("DELETE FROM search_index WHERE permalink = :permalink AND project_id = :project_id"),
+                text(
+                    "DELETE FROM search_index WHERE permalink = :permalink AND project_id = :project_id"
+                ),
                 {"permalink": search_index_row.permalink, "project_id": self.project_id},
             )
 
@@ -557,6 +559,48 @@ class SearchRepository:
             logger.debug(f"indexed row {search_index_row}")
             await session.commit()
 
+    async def bulk_index_items(self, search_index_rows: List[SearchIndexRow]):
+        """Index multiple items in a single batch operation.
+
+        Note: This method assumes that any existing records for the entity_id
+        have already been deleted (typically via delete_by_entity_id).
+
+        Args:
+            search_index_rows: List of SearchIndexRow objects to index
+        """
+        if not search_index_rows:
+            return
+
+        async with db.scoped_session(self.session_maker) as session:
+            # Prepare all insert data with project_id
+            insert_data_list = []
+            for row in search_index_rows:
+                insert_data = row.to_insert()
+                insert_data["project_id"] = self.project_id
+                insert_data_list.append(insert_data)
+
+            # Batch insert all records using executemany
+            await session.execute(
+                text("""
+                    INSERT INTO search_index (
+                        id, title, content_stems, content_snippet, permalink, file_path, type, metadata,
+                        from_id, to_id, relation_type,
+                        entity_id, category,
+                        created_at, updated_at,
+                        project_id
+                    ) VALUES (
+                        :id, :title, :content_stems, :content_snippet, :permalink, :file_path, :type, :metadata,
+                        :from_id, :to_id, :relation_type,
+                        :entity_id, :category,
+                        :created_at, :updated_at,
+                        :project_id
+                    )
+                """),
+                insert_data_list,
+            )
+            logger.debug(f"Bulk indexed {len(search_index_rows)} rows")
+            await session.commit()
+
     async def delete_by_entity_id(self, entity_id: int):
         """Delete an item from the search index by entity_id."""
         async with db.scoped_session(self.session_maker) as session:

basic_memory/schemas/__init__.py

@@ -48,6 +48,10 @@ from basic_memory.schemas.directory import (
     DirectoryNode,
 )
 
+from basic_memory.schemas.sync_report import (
+    SyncReportResponse,
+)
+
 # For convenient imports, export all models
 __all__ = [
     # Base
@@ -77,4 +81,6 @@ __all__ = [
     "ProjectInfoResponse",
     # Directory
     "DirectoryNode",
+    # Sync
+    "SyncReportResponse",
 ]

basic_memory/schemas/base.py

@@ -11,9 +11,10 @@ Key Concepts:
 4. Everything is stored in both SQLite and markdown files
 """
 
+import os
 import mimetypes
 import re
-from datetime import datetime, time
+from datetime import datetime, timedelta
 from pathlib import Path
 from typing import List, Optional, Annotated, Dict
 
@@ -23,7 +24,7 @@ from dateparser import parse
 from pydantic import BaseModel, BeforeValidator, Field, model_validator
 
 from basic_memory.config import ConfigManager
-from basic_memory.file_utils import sanitize_for_filename
+from basic_memory.file_utils import sanitize_for_filename, sanitize_for_folder
 from basic_memory.utils import generate_permalink
 
 
@@ -51,30 +52,47 @@ def to_snake_case(name: str) -> str:
 def parse_timeframe(timeframe: str) -> datetime:
     """Parse timeframe with special handling for 'today' and other natural language expressions.
 
+    Enforces a minimum 1-day lookback to handle timezone differences in distributed deployments.
+
     Args:
         timeframe: Natural language timeframe like 'today', '1d', '1 week ago', etc.
 
     Returns:
         datetime: The parsed datetime for the start of the timeframe, timezone-aware in local system timezone
+                 Always returns at least 1 day ago to handle timezone differences.
 
     Examples:
-        parse_timeframe('today') -> 2025-06-05 00:00:00-07:00 (start of today with local timezone)
+        parse_timeframe('today') -> 2025-06-04 14:50:00-07:00 (1 day ago, not start of today)
+        parse_timeframe('1h') -> 2025-06-04 14:50:00-07:00 (1 day ago, not 1 hour ago)
         parse_timeframe('1d') -> 2025-06-04 14:50:00-07:00 (24 hours ago with local timezone)
         parse_timeframe('1 week ago') -> 2025-05-29 14:50:00-07:00 (1 week ago with local timezone)
     """
     if timeframe.lower() == "today":
-        # Return start of today (00:00:00) in local timezone
-        naive_dt = datetime.combine(datetime.now().date(), time.min)
-        return naive_dt.astimezone()
+        # For "today", return 1 day ago to ensure we capture recent activity across timezones
+        # This handles the case where client and server are in different timezones
+        now = datetime.now()
+        one_day_ago = now - timedelta(days=1)
+        return one_day_ago.astimezone()
     else:
         # Use dateparser for other formats
         parsed = parse(timeframe)
         if not parsed:
             raise ValueError(f"Could not parse timeframe: {timeframe}")
-        
+
         # If the parsed datetime is naive, make it timezone-aware in local system timezone
         if parsed.tzinfo is None:
-            return parsed.astimezone()
+            parsed = parsed.astimezone()
+        else:
+            parsed = parsed
+
+        # Enforce minimum 1-day lookback to handle timezone differences
+        # This ensures we don't miss recent activity due to client/server timezone mismatches
+        now = datetime.now().astimezone()
+        one_day_ago = now - timedelta(days=1)
+
+        # If the parsed time is more recent than 1 day ago, use 1 day ago instead
+        if parsed > one_day_ago:
+            return one_day_ago
         else:
             return parsed
 
@@ -179,6 +197,7 @@ class Entity(BaseModel):
     """
 
     # private field to override permalink
+    # Use empty string "" as sentinel to indicate permalinks are explicitly disabled
     _permalink: Optional[str] = None
 
     title: str
@@ -192,6 +211,10 @@ class Entity(BaseModel):
         default="text/markdown",
     )
 
+    def __init__(self, **data):
+        data["folder"] = sanitize_for_folder(data.get("folder", ""))
+        super().__init__(**data)
+
     @property
     def safe_title(self) -> str:
         """
@@ -218,13 +241,18 @@ class Entity(BaseModel):
         """Get the file path for this entity based on its permalink."""
         safe_title = self.safe_title
         if self.content_type == "text/markdown":
-            return f"{self.folder}/{safe_title}.md" if self.folder else f"{safe_title}.md"
+            return (
+                os.path.join(self.folder, f"{safe_title}.md") if self.folder else f"{safe_title}.md"
+            )
         else:
-            return f"{self.folder}/{safe_title}" if self.folder else safe_title
+            return os.path.join(self.folder, safe_title) if self.folder else safe_title
 
     @property
-    def permalink(self) -> Permalink:
+    def permalink(self) -> Optional[Permalink]:
         """Get a url friendly path}."""
+        # Empty string is a sentinel value indicating permalinks are disabled
+        if self._permalink == "":
+            return None
         return self._permalink or generate_permalink(self.file_path)
 
     @model_validator(mode="after")

basic_memory/schemas/cloud.py

@@ -0,0 +1,46 @@
+"""Schemas for cloud-related API responses."""
+
+from pydantic import BaseModel, Field
+
+
+class TenantMountInfo(BaseModel):
+    """Response from /tenant/mount/info endpoint."""
+
+    tenant_id: str = Field(..., description="Unique identifier for the tenant")
+    bucket_name: str = Field(..., description="S3 bucket name for the tenant")
+
+
+class MountCredentials(BaseModel):
+    """Response from /tenant/mount/credentials endpoint."""
+
+    access_key: str = Field(..., description="S3 access key for mount")
+    secret_key: str = Field(..., description="S3 secret key for mount")
+
+
+class CloudProject(BaseModel):
+    """Representation of a cloud project."""
+
+    name: str = Field(..., description="Project name")
+    path: str = Field(..., description="Project path on cloud")
+
+
+class CloudProjectList(BaseModel):
+    """Response from /proxy/projects/projects endpoint."""
+
+    projects: list[CloudProject] = Field(default_factory=list, description="List of cloud projects")
+
+
+class CloudProjectCreateRequest(BaseModel):
+    """Request to create a new cloud project."""
+
+    name: str = Field(..., description="Project name")
+    path: str = Field(..., description="Project path (permalink)")
+    set_default: bool = Field(default=False, description="Set as default project")
+
+
+class CloudProjectCreateResponse(BaseModel):
+    """Response from creating a cloud project."""
+
+    name: str = Field(..., description="Created project name")
+    path: str = Field(..., description="Created project path")
+    message: str = Field(default="", description="Success message")

basic_memory/schemas/memory.py

@@ -1,10 +1,10 @@
 """Schemas for memory context."""
 
 from datetime import datetime
-from typing import List, Optional, Annotated, Sequence, Literal, Union
+from typing import List, Optional, Annotated, Sequence, Literal, Union, Dict
 
 from annotated_types import MinLen, MaxLen
-from pydantic import BaseModel, Field, BeforeValidator, TypeAdapter, ConfigDict
+from pydantic import BaseModel, Field, BeforeValidator, TypeAdapter, field_serializer
 
 from basic_memory.schemas.search import SearchItemType
 
@@ -26,6 +26,7 @@ def validate_memory_url_path(path: str) -> bool:
         >>> validate_memory_url_path("invalid://test")  # Contains protocol
         False
     """
+    # Empty paths are not valid
     if not path or not path.strip():
         return False
 
@@ -68,7 +69,13 @@ def normalize_memory_url(url: str | None) -> str:
         ValueError: Invalid memory URL path: 'memory//test' contains double slashes
     """
     if not url:
-        return ""
+        raise ValueError("Memory URL cannot be empty")
+
+    # Strip whitespace for consistency
+    url = url.strip()
+
+    if not url:
+        raise ValueError("Memory URL cannot be empty or whitespace")
 
     clean_path = url.removeprefix("memory://")
 
@@ -79,8 +86,6 @@ def normalize_memory_url(url: str | None) -> str:
             raise ValueError(f"Invalid memory URL path: '{clean_path}' contains protocol scheme")
         elif "//" in clean_path:
             raise ValueError(f"Invalid memory URL path: '{clean_path}' contains double slashes")
-        elif not clean_path.strip():
-            raise ValueError("Memory URL path cannot be empty or whitespace")
         else:
             raise ValueError(f"Invalid memory URL path: '{clean_path}' contains invalid characters")
 
@@ -117,21 +122,23 @@ def memory_url_path(url: memory_url) -> str:  # pyright: ignore
 
 class EntitySummary(BaseModel):
     """Simplified entity representation."""
-    
-    model_config = ConfigDict(json_encoders={datetime: lambda dt: dt.isoformat()})
 
     type: Literal["entity"] = "entity"
     permalink: Optional[str]
     title: str
     content: Optional[str] = None
     file_path: str
-    created_at: datetime
+    created_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
+
+    @field_serializer("created_at")
+    def serialize_created_at(self, dt: datetime) -> str:
+        return dt.isoformat()
 
 
 class RelationSummary(BaseModel):
     """Simplified relation representation."""
-    
-    model_config = ConfigDict(json_encoders={datetime: lambda dt: dt.isoformat()})
 
     type: Literal["relation"] = "relation"
     title: str
@@ -140,13 +147,17 @@ class RelationSummary(BaseModel):
     relation_type: str
     from_entity: Optional[str] = None
     to_entity: Optional[str] = None
-    created_at: datetime
+    created_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
+
+    @field_serializer("created_at")
+    def serialize_created_at(self, dt: datetime) -> str:
+        return dt.isoformat()
 
 
 class ObservationSummary(BaseModel):
     """Simplified observation representation."""
-    
-    model_config = ConfigDict(json_encoders={datetime: lambda dt: dt.isoformat()})
 
     type: Literal["observation"] = "observation"
     title: str
@@ -154,32 +165,42 @@ class ObservationSummary(BaseModel):
     permalink: str
     category: str
     content: str
-    created_at: datetime
+    created_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
+
+    @field_serializer("created_at")
+    def serialize_created_at(self, dt: datetime) -> str:
+        return dt.isoformat()
 
 
 class MemoryMetadata(BaseModel):
     """Simplified response metadata."""
-    
-    model_config = ConfigDict(json_encoders={datetime: lambda dt: dt.isoformat()})
 
     uri: Optional[str] = None
     types: Optional[List[SearchItemType]] = None
     depth: int
     timeframe: Optional[str] = None
-    generated_at: datetime
+    generated_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
     primary_count: Optional[int] = None  # Changed field name
     related_count: Optional[int] = None  # Changed field name
     total_results: Optional[int] = None  # For backward compatibility
     total_relations: Optional[int] = None
     total_observations: Optional[int] = None
 
+    @field_serializer("generated_at")
+    def serialize_generated_at(self, dt: datetime) -> str:
+        return dt.isoformat()
+
 
 class ContextResult(BaseModel):
     """Context result containing a primary item with its observations and related items."""
 
     primary_result: Annotated[
-        Union[EntitySummary, RelationSummary, ObservationSummary], 
-        Field(discriminator="type", description="Primary item")
+        Union[EntitySummary, RelationSummary, ObservationSummary],
+        Field(discriminator="type", description="Primary item"),
     ]
 
     observations: Sequence[ObservationSummary] = Field(
@@ -188,8 +209,7 @@ class ContextResult(BaseModel):
 
     related_results: Sequence[
         Annotated[
-            Union[EntitySummary, RelationSummary, ObservationSummary], 
-            Field(discriminator="type")
+            Union[EntitySummary, RelationSummary, ObservationSummary], Field(discriminator="type")
         ]
     ] = Field(description="Related items", default_factory=list)
 
@@ -207,3 +227,52 @@ class GraphContext(BaseModel):
 
     page: Optional[int] = None
     page_size: Optional[int] = None
+
+
+class ActivityStats(BaseModel):
+    """Statistics about activity across all projects."""
+
+    total_projects: int
+    active_projects: int = Field(description="Projects with activity in timeframe")
+    most_active_project: Optional[str] = None
+    total_items: int = Field(description="Total items across all projects")
+    total_entities: int = 0
+    total_relations: int = 0
+    total_observations: int = 0
+
+
+class ProjectActivity(BaseModel):
+    """Activity summary for a single project."""
+
+    project_name: str
+    project_path: str
+    activity: GraphContext = Field(description="The actual activity data for this project")
+    item_count: int = Field(description="Total items in this project's activity")
+    last_activity: Optional[
+        Annotated[datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})]
+    ] = Field(default=None, description="Most recent activity timestamp")
+    active_folders: List[str] = Field(default_factory=list, description="Most active folders")
+
+    @field_serializer("last_activity")
+    def serialize_last_activity(self, dt: Optional[datetime]) -> Optional[str]:
+        return dt.isoformat() if dt else None
+
+
+class ProjectActivitySummary(BaseModel):
+    """Summary of activity across all projects."""
+
+    projects: Dict[str, ProjectActivity] = Field(
+        description="Activity per project, keyed by project name"
+    )
+    summary: ActivityStats
+    timeframe: str = Field(description="The timeframe used for the query")
+    generated_at: Annotated[
+        datetime, Field(json_schema_extra={"type": "string", "format": "date-time"})
+    ]
+    guidance: Optional[str] = Field(
+        default=None, description="Assistant guidance for project selection and session management"
+    )
+
+    @field_serializer("generated_at")
+    def serialize_generated_at(self, dt: datetime) -> str:
+        return dt.isoformat()

basic_memory/schemas/project_info.py

@@ -2,6 +2,7 @@
 
 import os
 from datetime import datetime
+from pathlib import Path
 from typing import Dict, List, Optional, Any
 
 from pydantic import Field, BaseModel
@@ -78,16 +79,6 @@ class SystemStatus(BaseModel):
     timestamp: datetime = Field(description="Timestamp when the information was collected")
 
 
-class ProjectDetail(BaseModel):
-    """Detailed information about a project."""
-
-    path: str = Field(description="Path to the project directory")
-    active: bool = Field(description="Whether the project is active")
-    id: Optional[int] = Field(description="Database ID of the project if available")
-    is_default: bool = Field(description="Whether this is the default project")
-    permalink: str = Field(description="URL-friendly identifier for the project")
-
-
 class ProjectInfoResponse(BaseModel):
     """Response for the project_info tool."""
 
@@ -190,6 +181,14 @@ class ProjectItem(BaseModel):
     def permalink(self) -> str:  # pragma: no cover
         return generate_permalink(self.name)
 
+    @property
+    def home(self) -> Path:  # pragma: no cover
+        return Path(self.path).expanduser()
+
+    @property
+    def project_url(self) -> str:  # pragma: no cover
+        return f"/{generate_permalink(self.name)}"
+
 
 class ProjectList(BaseModel):
     """Response model for listing projects."""

basic_memory/schemas/sync_report.py

@@ -0,0 +1,48 @@
+"""Pydantic schemas for sync report responses."""
+
+from typing import TYPE_CHECKING, Dict, Set
+
+from pydantic import BaseModel, Field
+
+# avoid cirular imports
+if TYPE_CHECKING:
+    from basic_memory.sync.sync_service import SyncReport
+
+
+class SyncReportResponse(BaseModel):
+    """Report of file changes found compared to database state.
+
+    Used for API responses when scanning or syncing files.
+    """
+
+    new: Set[str] = Field(default_factory=set, description="Files on disk but not in database")
+    modified: Set[str] = Field(default_factory=set, description="Files with different checksums")
+    deleted: Set[str] = Field(default_factory=set, description="Files in database but not on disk")
+    moves: Dict[str, str] = Field(
+        default_factory=dict, description="Files moved (old_path -> new_path)"
+    )
+    checksums: Dict[str, str] = Field(
+        default_factory=dict, description="Current file checksums (path -> checksum)"
+    )
+    total: int = Field(description="Total number of changes")
+
+    @classmethod
+    def from_sync_report(cls, report: "SyncReport") -> "SyncReportResponse":
+        """Convert SyncReport dataclass to Pydantic model.
+
+        Args:
+            report: SyncReport dataclass from sync service
+
+        Returns:
+            SyncReportResponse with same data
+        """
+        return cls(
+            new=report.new,
+            modified=report.modified,
+            deleted=report.deleted,
+            moves=report.moves,
+            checksums=report.checksums,
+            total=report.total,
+        )
+
+    model_config = {"from_attributes": True}

basic_memory/services/context_service.py

@@ -100,20 +100,30 @@ class ContextService:
             f"Building context for URI: '{memory_url}' depth: '{depth}' since: '{since}' limit: '{limit}' offset: '{offset}'  max_related: '{max_related}'"
         )
 
+        normalized_path: Optional[str] = None
         if memory_url:
             path = memory_url_path(memory_url)
-            # Pattern matching - use search
-            if "*" in path:
-                logger.debug(f"Pattern search for '{path}'")
+            # Check for wildcards before normalization
+            has_wildcard = "*" in path
+
+            if has_wildcard:
+                # For wildcard patterns, normalize each segment separately to preserve the *
+                parts = path.split("*")
+                normalized_parts = [
+                    generate_permalink(part, split_extension=False) if part else ""
+                    for part in parts
+                ]
+                normalized_path = "*".join(normalized_parts)
+                logger.debug(f"Pattern search for '{normalized_path}'")
                 primary = await self.search_repository.search(
-                    permalink_match=path, limit=limit, offset=offset
+                    permalink_match=normalized_path, limit=limit, offset=offset
                 )
-
-            # Direct lookup for exact path
             else:
-                logger.debug(f"Direct lookup for '{path}'")
+                # For exact paths, normalize the whole thing
+                normalized_path = generate_permalink(path, split_extension=False)
+                logger.debug(f"Direct lookup for '{normalized_path}'")
                 primary = await self.search_repository.search(
-                    permalink=path, limit=limit, offset=offset
+                    permalink=normalized_path, limit=limit, offset=offset
                 )
         else:
             logger.debug(f"Build context for '{types}'")
@@ -151,7 +161,7 @@ class ContextService:
 
         # Create metadata dataclass
         metadata = ContextMetadata(
-            uri=memory_url_path(memory_url) if memory_url else None,
+            uri=normalized_path if memory_url else None,
             types=types,
             depth=depth,
             timeframe=since.isoformat() if since else None,
@@ -246,7 +256,11 @@ class ContextService:
         values = ", ".join([f"('{t}', {i})" for t, i in type_id_pairs])
 
         # Parameters for bindings - include project_id for security filtering
-        params = {"max_depth": max_depth, "max_results": max_results, "project_id": self.search_repository.project_id}
+        params = {
+            "max_depth": max_depth,
+            "max_results": max_results,
+            "project_id": self.search_repository.project_id,
+        }
 
         # Build date and timeframe filters conditionally based on since parameter
         if since:
@@ -258,7 +272,7 @@ class ContextService:
             date_filter = ""
             relation_date_filter = ""
             timeframe_condition = ""
-        
+
         # Add project filtering for security - ensure all entities and relations belong to the same project
         project_filter = "AND e.project_id = :project_id"
         relation_project_filter = "AND e_from.project_id = :project_id"