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

basic_memory/models/knowledge.py

@@ -74,8 +74,14 @@ class Entity(Base):
     checksum: Mapped[Optional[str]] = mapped_column(String, nullable=True)
 
     # Metadata and tracking
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now().astimezone())
-    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now().astimezone(), onupdate=lambda: datetime.now().astimezone())
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now().astimezone()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now().astimezone(),
+        onupdate=lambda: datetime.now().astimezone(),
+    )
 
     # Relationships
     project = relationship("Project", back_populates="entities")
@@ -104,15 +110,15 @@ class Entity(Base):
     def is_markdown(self):
         """Check if the entity is a markdown file."""
         return self.content_type == "text/markdown"
-    
+
     def __getattribute__(self, name):
         """Override attribute access to ensure datetime fields are timezone-aware."""
         value = super().__getattribute__(name)
-        
+
         # Ensure datetime fields are timezone-aware
-        if name in ('created_at', 'updated_at') and isinstance(value, datetime):
+        if name in ("created_at", "updated_at") and isinstance(value, datetime):
             return ensure_timezone_aware(value)
-        
+
         return value
 
     def __repr__(self) -> str:

basic_memory/models/project.py

@@ -52,9 +52,13 @@ class Project(Base):
     is_default: Mapped[Optional[bool]] = mapped_column(Boolean, default=None, nullable=True)
 
     # Timestamps
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
     updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
     )
 
     # Define relationships to entities, observations, and relations

basic_memory/repository/entity_repository.py

@@ -101,11 +101,10 @@ class EntityRepository(Repository[Entity]):
         return list(result.scalars().all())
 
     async def upsert_entity(self, entity: Entity) -> Entity:
-        """Insert or update entity using a hybrid approach.
+        """Insert or update entity using simple try/catch with database-level conflict resolution.
 
-        This method provides a cleaner alternative to the try/catch approach
-        for handling permalink and file_path conflicts. It first tries direct
-        insertion, then handles conflicts intelligently.
+        Handles file_path race conditions by checking for existing entity on IntegrityError.
+        For permalink conflicts, generates a unique permalink with numeric suffix.
 
         Args:
             entity: The entity to insert or update
@@ -113,50 +112,12 @@ class EntityRepository(Repository[Entity]):
         Returns:
             The inserted or updated entity
         """
-
         async with db.scoped_session(self.session_maker) as session:
             # Set project_id if applicable and not already set
             self._set_project_id_if_needed(entity)
 
-            # Check for existing entity with same file_path first
-            existing_by_path = await session.execute(
-                select(Entity).where(
-                    Entity.file_path == entity.file_path, Entity.project_id == entity.project_id
-                )
-            )
-            existing_path_entity = existing_by_path.scalar_one_or_none()
-
-            if existing_path_entity:
-                # Update existing entity with same file path
-                for key, value in {
-                    "title": entity.title,
-                    "entity_type": entity.entity_type,
-                    "entity_metadata": entity.entity_metadata,
-                    "content_type": entity.content_type,
-                    "permalink": entity.permalink,
-                    "checksum": entity.checksum,
-                    "updated_at": entity.updated_at,
-                }.items():
-                    setattr(existing_path_entity, key, value)
-
-                await session.flush()
-                # Return with relationships loaded
-                query = (
-                    self.select()
-                    .where(Entity.file_path == entity.file_path)
-                    .options(*self.get_load_options())
-                )
-                result = await session.execute(query)
-                found = result.scalar_one_or_none()
-                if not found:  # pragma: no cover
-                    raise RuntimeError(
-                        f"Failed to retrieve entity after update: {entity.file_path}"
-                    )
-                return found
-
-            # No existing entity with same file_path, try insert
+            # Try simple insert first
             try:
-                # Simple insert for new entity
                 session.add(entity)
                 await session.flush()
 
@@ -175,20 +136,20 @@ class EntityRepository(Repository[Entity]):
                 return found
 
             except IntegrityError:
-                # Could be either file_path or permalink conflict
                 await session.rollback()
 
-                # Check if it's a file_path conflict (race condition)
-                existing_by_path_check = await session.execute(
-                    select(Entity).where(
+                # Re-query after rollback to get a fresh, attached entity
+                existing_result = await session.execute(
+                    select(Entity)
+                    .where(
                         Entity.file_path == entity.file_path, Entity.project_id == entity.project_id
                     )
+                    .options(*self.get_load_options())
                 )
-                race_condition_entity = existing_by_path_check.scalar_one_or_none()
+                existing_entity = existing_result.scalar_one_or_none()
 
-                if race_condition_entity:
-                    # Race condition: file_path conflict detected after our initial check
-                    # Update the existing entity instead
+                if existing_entity:
+                    # File path conflict - update the existing entity
                     for key, value in {
                         "title": entity.title,
                         "entity_type": entity.entity_type,
@@ -198,25 +159,22 @@ class EntityRepository(Repository[Entity]):
                         "checksum": entity.checksum,
                         "updated_at": entity.updated_at,
                     }.items():
-                        setattr(race_condition_entity, key, value)
-
-                    await session.flush()
-                    # Return the updated entity with relationships loaded
-                    query = (
-                        self.select()
-                        .where(Entity.file_path == entity.file_path)
-                        .options(*self.get_load_options())
-                    )
-                    result = await session.execute(query)
-                    found = result.scalar_one_or_none()
-                    if not found:  # pragma: no cover
-                        raise RuntimeError(
-                            f"Failed to retrieve entity after race condition update: {entity.file_path}"
-                        )
-                    return found
+                        setattr(existing_entity, key, value)
+
+                    # Clear and re-add observations
+                    existing_entity.observations.clear()
+                    for obs in entity.observations:
+                        obs.entity_id = existing_entity.id
+                        existing_entity.observations.append(obs)
+
+                    await session.commit()
+                    return existing_entity
+
                 else:
-                    # Must be permalink conflict - generate unique permalink
-                    return await self._handle_permalink_conflict(entity, session)
+                    # No file_path conflict - must be permalink conflict
+                    # Generate unique permalink and retry
+                    entity = await self._handle_permalink_conflict(entity, session)
+                    return entity
 
     async def _handle_permalink_conflict(self, entity: Entity, session: AsyncSession) -> Entity:
         """Handle permalink conflicts by generating a unique permalink."""
@@ -237,18 +195,7 @@ class EntityRepository(Repository[Entity]):
                 break
             suffix += 1
 
-        # Insert with unique permalink (no conflict possible now)
+        # Insert with unique permalink
         session.add(entity)
         await session.flush()
-
-        # Return the inserted entity with relationships loaded
-        query = (
-            self.select()
-            .where(Entity.file_path == entity.file_path)
-            .options(*self.get_load_options())
-        )
-        result = await session.execute(query)
-        found = result.scalar_one_or_none()
-        if not found:  # pragma: no cover
-            raise RuntimeError(f"Failed to retrieve entity after insert: {entity.file_path}")
-        return found
+        return entity

basic_memory/repository/relation_repository.py

@@ -73,5 +73,18 @@ class RelationRepository(Repository[Relation]):
         result = await self.execute_query(query)
         return result.scalars().all()
 
+    async def find_unresolved_relations_for_entity(self, entity_id: int) -> Sequence[Relation]:
+        """Find unresolved relations for a specific entity.
+
+        Args:
+            entity_id: The entity whose unresolved outgoing relations to find.
+
+        Returns:
+            List of unresolved relations where this entity is the source.
+        """
+        query = select(Relation).filter(Relation.from_id == entity_id, Relation.to_id.is_(None))
+        result = await self.execute_query(query)
+        return result.scalars().all()
+
     def get_load_options(self) -> List[LoaderOption]:
         return [selectinload(Relation.from_entity), selectinload(Relation.to_entity)]

basic_memory/repository/repository.py

@@ -10,13 +10,13 @@ from sqlalchemy import (
     Executable,
     inspect,
     Result,
-    Column,
     and_,
     delete,
 )
 from sqlalchemy.exc import NoResultFound
 from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
 from sqlalchemy.orm.interfaces import LoaderOption
+from sqlalchemy.sql.elements import ColumnElement
 
 from basic_memory import db
 from basic_memory.models import Base
@@ -38,7 +38,7 @@ class Repository[T: Base]:
         if Model:
             self.Model = Model
             self.mapper = inspect(self.Model).mapper
-            self.primary_key: Column[Any] = self.mapper.primary_key[0]
+            self.primary_key: ColumnElement[Any] = self.mapper.primary_key[0]
             self.valid_columns = [column.key for column in self.mapper.columns]
             # Check if this model has a project_id column
             self.has_project_id = "project_id" in self.valid_columns

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},
             )
 

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()