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

basic_memory/schemas/memory.py

@@ -1,10 +1,10 @@
 """Schemas for memory context."""
 
 from datetime import datetime
-from typing import List, Optional, Annotated, Sequence
+from typing import List, Optional, Annotated, Sequence, Literal, Union, Dict
 
 from annotated_types import MinLen, MaxLen
-from pydantic import BaseModel, Field, BeforeValidator, TypeAdapter
+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")
 
@@ -118,37 +123,55 @@ def memory_url_path(url: memory_url) -> str:  # pyright: ignore
 class EntitySummary(BaseModel):
     """Simplified entity representation."""
 
-    type: str = "entity"
+    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."""
 
-    type: str = "relation"
+    type: Literal["relation"] = "relation"
     title: str
     file_path: str
     permalink: str
     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."""
 
-    type: str = "observation"
+    type: Literal["observation"] = "observation"
     title: str
     file_path: str
     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):
@@ -158,28 +181,37 @@ class MemoryMetadata(BaseModel):
     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: EntitySummary | RelationSummary | ObservationSummary = Field(
-        description="Primary item"
-    )
+    primary_result: Annotated[
+        Union[EntitySummary, RelationSummary, ObservationSummary],
+        Field(discriminator="type", description="Primary item"),
+    ]
 
     observations: Sequence[ObservationSummary] = Field(
         description="Observations belonging to this entity", default_factory=list
     )
 
-    related_results: Sequence[EntitySummary | RelationSummary | ObservationSummary] = Field(
-        description="Related items", default_factory=list
-    )
+    related_results: Sequence[
+        Annotated[
+            Union[EntitySummary, RelationSummary, ObservationSummary], Field(discriminator="type")
+        ]
+    ] = Field(description="Related items", default_factory=list)
 
 
 class GraphContext(BaseModel):
@@ -195,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.name)
+
+    @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,
@@ -245,8 +255,12 @@ class ContextService:
         # For compatibility with the old query, we still need this for filtering
         values = ", ".join([f"('{t}', {i})" for t, i in type_id_pairs])
 
-        # Parameters for bindings
-        params = {"max_depth": max_depth, "max_results": max_results}
+        # 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,
+        }
 
         # Build date and timeframe filters conditionally based on since parameter
         if since:
@@ -259,6 +273,10 @@ class ContextService:
             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"
+
         # Use a CTE that operates directly on entity and relation tables
         # This avoids the overhead of the search_index virtual table
         query = text(f"""
@@ -284,6 +302,7 @@ class ContextService:
             FROM entity e
             WHERE e.id IN ({entity_id_values})
             {date_filter}
+            {project_filter}
 
             UNION ALL
 
@@ -314,8 +333,12 @@ class ContextService:
             JOIN entity e_from ON (
                 r.from_id = e_from.id
                 {relation_date_filter}
+                {relation_project_filter}
             )
+            LEFT JOIN entity e_to ON (r.to_id = e_to.id)
             WHERE eg.depth < :max_depth
+            -- Ensure to_entity (if exists) also belongs to same project
+            AND (r.to_id IS NULL OR e_to.project_id = :project_id)
 
             UNION ALL
 
@@ -348,6 +371,7 @@ class ContextService:
                     ELSE eg.from_id
                 END
                 {date_filter}
+                {project_filter}
             )
             WHERE eg.depth < :max_depth
             -- Only include entities connected by relations within timeframe if specified

basic_memory/services/directory_service.py

@@ -106,8 +106,15 @@ class DirectoryService:
             List of DirectoryNode objects matching the criteria
         """
         # Normalize directory path
+        # Strip ./ prefix if present (handles relative path notation)
+        if dir_name.startswith("./"):
+            dir_name = dir_name[2:]  # Remove "./" prefix
+
+        # Ensure path starts with "/"
         if not dir_name.startswith("/"):
             dir_name = f"/{dir_name}"
+
+        # Remove trailing slashes except for root
         if dir_name != "/" and dir_name.endswith("/"):
             dir_name = dir_name.rstrip("/")
 

basic_memory/services/entity_service.py

@@ -9,7 +9,12 @@ from loguru import logger
 from sqlalchemy.exc import IntegrityError
 
 from basic_memory.config import ProjectConfig, BasicMemoryConfig
-from basic_memory.file_utils import has_frontmatter, parse_frontmatter, remove_frontmatter
+from basic_memory.file_utils import (
+    has_frontmatter,
+    parse_frontmatter,
+    remove_frontmatter,
+    dump_frontmatter,
+)
 from basic_memory.markdown import EntityMarkdown
 from basic_memory.markdown.entity_parser import EntityParser
 from basic_memory.markdown.utils import entity_model_from_markdown, schema_to_markdown
@@ -37,6 +42,7 @@ class EntityService(BaseService[EntityModel]):
         relation_repository: RelationRepository,
         file_service: FileService,
         link_resolver: LinkResolver,
+        app_config: Optional[BasicMemoryConfig] = None,
     ):
         super().__init__(entity_repository)
         self.observation_repository = observation_repository
@@ -44,6 +50,7 @@ class EntityService(BaseService[EntityModel]):
         self.entity_parser = entity_parser
         self.file_service = file_service
         self.link_resolver = link_resolver
+        self.app_config = app_config
 
     async def detect_file_path_conflicts(self, file_path: str) -> List[Entity]:
         """Detect potential file path conflicts for a given file path.
@@ -91,7 +98,7 @@ class EntityService(BaseService[EntityModel]):
 
         Enhanced to detect and handle character-related conflicts.
         """
-        file_path_str = str(file_path)
+        file_path_str = Path(file_path).as_posix()
 
         # Check for potential file path conflicts before resolving permalink
         conflicts = await self.detect_file_path_conflicts(file_path_str)
@@ -119,7 +126,7 @@ class EntityService(BaseService[EntityModel]):
         if markdown and markdown.frontmatter.permalink:
             desired_permalink = markdown.frontmatter.permalink
         else:
-            desired_permalink = generate_permalink(file_path)
+            desired_permalink = generate_permalink(file_path_str)
 
         # Make unique if needed - enhanced to handle character conflicts
         permalink = desired_permalink
@@ -139,10 +146,11 @@ class EntityService(BaseService[EntityModel]):
             f"Creating or updating entity: {schema.file_path}, permalink: {schema.permalink}"
         )
 
-        # Try to find existing entity using smart resolution
-        existing = await self.link_resolver.resolve_link(
-            schema.file_path
-        ) or await self.link_resolver.resolve_link(schema.permalink)
+        # Try to find existing entity using strict resolution (no fuzzy search)
+        # This prevents incorrectly matching similar file paths like "Node A.md" and "Node C.md"
+        existing = await self.link_resolver.resolve_link(schema.file_path, strict=True)
+        if not existing and schema.permalink:
+            existing = await self.link_resolver.resolve_link(schema.permalink, strict=True)
 
         if existing:
             logger.debug(f"Found existing entity: {existing.file_path}")
@@ -189,14 +197,20 @@ class EntityService(BaseService[EntityModel]):
                     relations=[],
                 )
 
-        # Get unique permalink (prioritizing content frontmatter)
-        permalink = await self.resolve_permalink(file_path, content_markdown)
-        schema._permalink = permalink
+        # Get unique permalink (prioritizing content frontmatter) unless disabled
+        if self.app_config and self.app_config.disable_permalinks:
+            # Use empty string as sentinel to indicate permalinks are disabled
+            # The permalink property will return None when it sees empty string
+            schema._permalink = ""
+        else:
+            # Generate and set permalink
+            permalink = await self.resolve_permalink(file_path, content_markdown)
+            schema._permalink = permalink
 
         post = await schema_to_markdown(schema)
 
         # write file
-        final_content = frontmatter.dumps(post, sort_keys=False)
+        final_content = dump_frontmatter(post)
         checksum = await self.file_service.write_file(file_path, final_content)
 
         # parse entity from file
@@ -249,15 +263,16 @@ class EntityService(BaseService[EntityModel]):
                     relations=[],
                 )
 
-        # Check if we need to update the permalink based on content frontmatter
+        # Check if we need to update the permalink based on content frontmatter (unless disabled)
         new_permalink = entity.permalink  # Default to existing
-        if content_markdown and content_markdown.frontmatter.permalink:
-            # Resolve permalink with the new content frontmatter
-            resolved_permalink = await self.resolve_permalink(file_path, content_markdown)
-            if resolved_permalink != entity.permalink:
-                new_permalink = resolved_permalink
-                # Update the schema to use the new permalink
-                schema._permalink = new_permalink
+        if self.app_config and not self.app_config.disable_permalinks:
+            if content_markdown and content_markdown.frontmatter.permalink:
+                # Resolve permalink with the new content frontmatter
+                resolved_permalink = await self.resolve_permalink(file_path, content_markdown)
+                if resolved_permalink != entity.permalink:
+                    new_permalink = resolved_permalink
+                    # Update the schema to use the new permalink
+                    schema._permalink = new_permalink
 
         # Create post with new content from schema
         post = await schema_to_markdown(schema)
@@ -273,7 +288,7 @@ class EntityService(BaseService[EntityModel]):
         merged_post = frontmatter.Post(post.content, **existing_markdown.frontmatter.metadata)
 
         # write file
-        final_content = frontmatter.dumps(merged_post, sort_keys=False)
+        final_content = dump_frontmatter(merged_post)
         checksum = await self.file_service.write_file(file_path, final_content)
 
         # parse entity from file
@@ -283,7 +298,7 @@ class EntityService(BaseService[EntityModel]):
         entity = await self.update_entity_and_observations(file_path, entity_markdown)
 
         # add relations
-        await self.update_entity_relations(str(file_path), entity_markdown)
+        await self.update_entity_relations(file_path.as_posix(), entity_markdown)
 
         # Set final checksum to match file
         entity = await self.repository.update(entity.id, {"checksum": checksum})
@@ -374,7 +389,7 @@ class EntityService(BaseService[EntityModel]):
         """
         logger.debug(f"Updating entity and observations: {file_path}")
 
-        db_entity = await self.repository.get_by_file_path(str(file_path))
+        db_entity = await self.repository.get_by_file_path(file_path.as_posix())
 
         # Clear observations for entity
         await self.observation_repository.delete_by_fields(entity_id=db_entity.id)
@@ -417,34 +432,47 @@ class EntityService(BaseService[EntityModel]):
         # Clear existing relations first
         await self.relation_repository.delete_outgoing_relations_from_entity(db_entity.id)
 
-        # Process each relation
-        for rel in markdown.relations:
-            # Resolve the target permalink
-            target_entity = await self.link_resolver.resolve_link(
-                rel.target,
-            )
-
-            # if the target is found, store the id
-            target_id = target_entity.id if target_entity else None
-            # if the target is found, store the title, otherwise add the target for a "forward link"
-            target_name = target_entity.title if target_entity else rel.target
-
-            # Create the relation
-            relation = Relation(
-                from_id=db_entity.id,
-                to_id=target_id,
-                to_name=target_name,
-                relation_type=rel.type,
-                context=rel.context,
-            )
-            try:
-                await self.relation_repository.add(relation)
-            except IntegrityError:
-                # Unique constraint violation - relation already exists
-                logger.debug(
-                    f"Skipping duplicate relation {rel.type} from {db_entity.permalink} target: {rel.target}"
+        # Batch resolve all relation targets in parallel
+        if markdown.relations:
+            import asyncio
+
+            # Create tasks for all relation lookups
+            lookup_tasks = [
+                self.link_resolver.resolve_link(rel.target) for rel in markdown.relations
+            ]
+
+            # Execute all lookups in parallel
+            resolved_entities = await asyncio.gather(*lookup_tasks, return_exceptions=True)
+
+            # Process results and create relation records
+            for rel, resolved in zip(markdown.relations, resolved_entities):
+                # Handle exceptions from gather and None results
+                target_entity: Optional[Entity] = None
+                if not isinstance(resolved, Exception):
+                    # Type narrowing: resolved is Optional[Entity] here, not Exception
+                    target_entity = resolved  # type: ignore
+
+                # if the target is found, store the id
+                target_id = target_entity.id if target_entity else None
+                # if the target is found, store the title, otherwise add the target for a "forward link"
+                target_name = target_entity.title if target_entity else rel.target
+
+                # Create the relation
+                relation = Relation(
+                    from_id=db_entity.id,
+                    to_id=target_id,
+                    to_name=target_name,
+                    relation_type=rel.type,
+                    context=rel.context,
                 )
-                continue
+                try:
+                    await self.relation_repository.add(relation)
+                except IntegrityError:
+                    # Unique constraint violation - relation already exists
+                    logger.debug(
+                        f"Skipping duplicate relation {rel.type} from {db_entity.permalink} target: {rel.target}"
+                    )
+                    continue
 
         return await self.repository.get_by_file_path(path)
 
@@ -498,7 +526,7 @@ class EntityService(BaseService[EntityModel]):
 
         # Update entity and its relationships
         entity = await self.update_entity_and_observations(file_path, entity_markdown)
-        await self.update_entity_relations(str(file_path), entity_markdown)
+        await self.update_entity_relations(file_path.as_posix(), entity_markdown)
 
         # Set final checksum to match file
         entity = await self.repository.update(entity.id, {"checksum": checksum})
@@ -728,8 +756,10 @@ class EntityService(BaseService[EntityModel]):
             # 6. Prepare database updates
             updates = {"file_path": destination_path}
 
-            # 7. Update permalink if configured or if entity has null permalink
-            if app_config.update_permalinks_on_move or old_permalink is None:
+            # 7. Update permalink if configured or if entity has null permalink (unless disabled)
+            if not app_config.disable_permalinks and (
+                app_config.update_permalinks_on_move or old_permalink is None
+            ):
                 # Generate new permalink from destination path
                 new_permalink = await self.resolve_permalink(destination_path)