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

basic_memory/models/knowledge.py

@@ -1,6 +1,7 @@
 """Knowledge graph models."""
 
 from datetime import datetime
+from basic_memory.utils import ensure_timezone_aware
 from typing import Optional
 
 from sqlalchemy import (
@@ -73,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)
-    updated_at: Mapped[datetime] = mapped_column(DateTime)
+    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,6 +111,16 @@ class Entity(Base):
         """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):
+            return ensure_timezone_aware(value)
+
+        return value
+
     def __repr__(self) -> str:
         return f"Entity(id={self.id}, name='{self.title}', type='{self.entity_type}'"
 

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

@@ -57,7 +57,7 @@ class EntityRepository(Repository[Entity]):
         """
         query = (
             self.select()
-            .where(Entity.file_path == str(file_path))
+            .where(Entity.file_path == Path(file_path).as_posix())
             .options(*self.get_load_options())
         )
         return await self.find_one(query)
@@ -68,7 +68,7 @@ class EntityRepository(Repository[Entity]):
         Args:
             file_path: Path to the entity file (will be converted to string internally)
         """
-        return await self.delete_by_fields(file_path=str(file_path))
+        return await self.delete_by_fields(file_path=Path(file_path).as_posix())
 
     def get_load_options(self) -> List[LoaderOption]:
         """Get SQLAlchemy loader options for eager loading relationships."""
@@ -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/project_repository.py

@@ -46,7 +46,7 @@ class ProjectRepository(Repository[Project]):
         Args:
             path: Path to the project directory (will be converted to string internally)
         """
-        query = self.select().where(Project.path == str(path))
+        query = self.select().where(Project.path == Path(path).as_posix())
         return await self.find_one(query)
 
     async def get_default_project(self) -> Optional[Project]:

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

@@ -6,6 +6,7 @@ import time
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, Dict, List, Optional
+from pathlib import Path
 
 from loguru import logger
 from sqlalchemy import Executable, Result, text
@@ -59,8 +60,11 @@ class SearchIndexRow:
         if not self.type == SearchItemType.ENTITY.value and not self.file_path:
             return ""
 
+        # Normalize path separators to handle both Windows (\) and Unix (/) paths
+        normalized_path = Path(self.file_path).as_posix()
+
         # Split the path by slashes
-        parts = self.file_path.split("/")
+        parts = normalized_path.split("/")
 
         # If there's only one part (e.g., "README.md"), it's at the root
         if len(parts) <= 1:
@@ -523,8 +527,10 @@ 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"),
-                {"permalink": search_index_row.permalink},
+                text(
+                    "DELETE FROM search_index WHERE permalink = :permalink AND project_id = :project_id"
+                ),
+                {"permalink": search_index_row.permalink, "project_id": self.project_id},
             )
 
             # Prepare data for insert with 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
 
@@ -22,6 +23,8 @@ 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, sanitize_for_folder
 from basic_memory.utils import generate_permalink
 
 
@@ -49,26 +52,49 @@ 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
+        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 (start of today)
-        parse_timeframe('1d') -> 2025-06-04 14:50:00 (24 hours ago)
-        parse_timeframe('1 week ago') -> 2025-05-29 14:50:00 (1 week ago)
+        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)
-        return datetime.combine(datetime.now().date(), time.min)
+        # 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}")
-        return parsed
+
+        # If the parsed datetime is naive, make it timezone-aware in local system timezone
+        if parsed.tzinfo is None:
+            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
 
 
 def validate_timeframe(timeframe: str) -> str:
@@ -85,7 +111,7 @@ def validate_timeframe(timeframe: str) -> str:
     parsed = parse_timeframe(timeframe)
 
     # Convert to duration
-    now = datetime.now()
+    now = datetime.now().astimezone()
     if parsed > now:
         raise ValueError("Timeframe cannot be in the future")
 
@@ -171,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
@@ -184,17 +211,48 @@ 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:
+        """
+        A sanitized version of the title, which is safe for use on the filesystem. For example,
+        a title of "Coupon Enable/Disable Feature" should create a the file as "Coupon Enable-Disable Feature.md"
+        instead of creating a file named "Disable Feature.md" beneath the "Coupon Enable" directory.
+
+        Replaces POSIX and/or Windows style slashes as well as a few other characters that are not safe for filenames.
+        If kebab_filenames is True, then behavior is consistent with transformation used when generating permalink
+        strings (e.g. "Coupon Enable/Disable Feature" -> "coupon-enable-disable-feature").
+        """
+        fixed_title = sanitize_for_filename(self.title)
+
+        app_config = ConfigManager().config
+        use_kebab_case = app_config.kebab_filenames
+
+        if use_kebab_case:
+            fixed_title = generate_permalink(file_path=fixed_title, split_extension=False)
+
+        return fixed_title
+
     @property
     def file_path(self):
         """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}/{self.title}.md" if self.folder else f"{self.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}/{self.title}" if self.folder else self.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")