basic-memory 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl

basic_memory/schemas/base.py

@@ -13,7 +13,7 @@ Key Concepts:
 
 import mimetypes
 import re
-from datetime import datetime
+from datetime import datetime, time
 from pathlib import Path
 from typing import List, Optional, Annotated, Dict
 
@@ -46,15 +46,43 @@ def to_snake_case(name: str) -> str:
     return s2.lower()
 
 
+def parse_timeframe(timeframe: str) -> datetime:
+    """Parse timeframe with special handling for 'today' and other natural language expressions.
+
+    Args:
+        timeframe: Natural language timeframe like 'today', '1d', '1 week ago', etc.
+
+    Returns:
+        datetime: The parsed datetime for the start of the timeframe
+
+    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)
+    """
+    if timeframe.lower() == "today":
+        # Return start of today (00:00:00)
+        return datetime.combine(datetime.now().date(), time.min)
+    else:
+        # Use dateparser for other formats
+        parsed = parse(timeframe)
+        if not parsed:
+            raise ValueError(f"Could not parse timeframe: {timeframe}")
+        return parsed
+
+
 def validate_timeframe(timeframe: str) -> str:
     """Convert human readable timeframes to a duration relative to the current time."""
     if not isinstance(timeframe, str):
         raise ValueError("Timeframe must be a string")
 
-    # Parse relative time expression
-    parsed = parse(timeframe)
-    if not parsed:
-        raise ValueError(f"Could not parse timeframe: {timeframe}")
+    # Preserve special timeframe strings that need custom handling
+    special_timeframes = ["today"]
+    if timeframe.lower() in special_timeframes:
+        return timeframe.lower()
+
+    # Parse relative time expression using our enhanced parser
+    parsed = parse_timeframe(timeframe)
 
     # Convert to duration
     now = datetime.now()

basic_memory/schemas/directory.py

@@ -0,0 +1,30 @@
+"""Schemas for directory tree operations."""
+
+from datetime import datetime
+from typing import List, Optional, Literal
+
+from pydantic import BaseModel
+
+
+class DirectoryNode(BaseModel):
+    """Directory node in file system."""
+
+    name: str
+    file_path: Optional[str] = None  # Original path without leading slash (matches DB)
+    directory_path: str  # Path with leading slash for directory navigation
+    type: Literal["directory", "file"]
+    children: List["DirectoryNode"] = []  # Default to empty list
+    title: Optional[str] = None
+    permalink: Optional[str] = None
+    entity_id: Optional[int] = None
+    entity_type: Optional[str] = None
+    content_type: Optional[str] = None
+    updated_at: Optional[datetime] = None
+
+    @property
+    def has_children(self) -> bool:
+        return bool(self.children)
+
+
+# Support for recursive model
+DirectoryNode.model_rebuild()

basic_memory/schemas/importer.py

@@ -0,0 +1,34 @@
+"""Schemas for import services."""
+
+from typing import Dict, Optional
+
+from pydantic import BaseModel
+
+
+class ImportResult(BaseModel):
+    """Common import result schema."""
+
+    import_count: Dict[str, int]
+    success: bool
+    error_message: Optional[str] = None
+
+
+class ChatImportResult(ImportResult):
+    """Result schema for chat imports."""
+
+    conversations: int = 0
+    messages: int = 0
+
+
+class ProjectImportResult(ImportResult):
+    """Result schema for project imports."""
+
+    documents: int = 0
+    prompts: int = 0
+
+
+class EntityImportResult(ImportResult):
+    """Result schema for entity imports."""
+
+    entities: int = 0
+    relations: int = 0

basic_memory/schemas/memory.py

@@ -9,8 +9,44 @@ from pydantic import BaseModel, Field, BeforeValidator, TypeAdapter
 from basic_memory.schemas.search import SearchItemType
 
 
+def validate_memory_url_path(path: str) -> bool:
+    """Validate that a memory URL path is well-formed.
+
+    Args:
+        path: The path part of a memory URL (without memory:// prefix)
+
+    Returns:
+        True if the path is valid, False otherwise
+
+    Examples:
+        >>> validate_memory_url_path("specs/search")
+        True
+        >>> validate_memory_url_path("memory//test")  # Double slash
+        False
+        >>> validate_memory_url_path("invalid://test")  # Contains protocol
+        False
+    """
+    if not path or not path.strip():
+        return False
+
+    # Check for invalid protocol schemes within the path first (more specific)
+    if "://" in path:
+        return False
+
+    # Check for double slashes (except at the beginning for absolute paths)
+    if "//" in path:
+        return False
+
+    # Check for invalid characters (excluding * which is used for pattern matching)
+    invalid_chars = {"<", ">", '"', "|", "?"}
+    if any(char in path for char in invalid_chars):
+        return False
+
+    return True
+
+
 def normalize_memory_url(url: str | None) -> str:
-    """Normalize a MemoryUrl string.
+    """Normalize a MemoryUrl string with validation.
 
     Args:
         url: A path like "specs/search" or "memory://specs/search"
@@ -18,22 +54,43 @@ def normalize_memory_url(url: str | None) -> str:
     Returns:
         Normalized URL starting with memory://
 
+    Raises:
+        ValueError: If the URL path is malformed
+
     Examples:
         >>> normalize_memory_url("specs/search")
         'memory://specs/search'
         >>> normalize_memory_url("memory://specs/search")
         'memory://specs/search'
+        >>> normalize_memory_url("memory//test")
+        Traceback (most recent call last):
+        ...
+        ValueError: Invalid memory URL path: 'memory//test' contains double slashes
     """
     if not url:
         return ""
 
     clean_path = url.removeprefix("memory://")
+
+    # Validate the extracted path
+    if not validate_memory_url_path(clean_path):
+        # Provide specific error messages for common issues
+        if "://" in clean_path:
+            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")
+
     return f"memory://{clean_path}"
 
 
 MemoryUrl = Annotated[
     str,
     BeforeValidator(str.strip),  # Clean whitespace
+    BeforeValidator(normalize_memory_url),  # Validate and normalize the URL
     MinLen(1),
     MaxLen(2028),
 ]
@@ -100,27 +157,41 @@ class MemoryMetadata(BaseModel):
     uri: Optional[str] = None
     types: Optional[List[SearchItemType]] = None
     depth: int
-    timeframe: str
+    timeframe: Optional[str] = None
     generated_at: datetime
-    total_results: int
-    total_relations: int
+    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
 
 
-class GraphContext(BaseModel):
-    """Complete context response."""
+class ContextResult(BaseModel):
+    """Context result containing a primary item with its observations and related items."""
+
+    primary_result: EntitySummary | RelationSummary | ObservationSummary = Field(
+        description="Primary item"
+    )
 
-    # Direct matches
-    primary_results: Sequence[EntitySummary | RelationSummary | ObservationSummary] = Field(
-        description="results directly matching URI"
+    observations: Sequence[ObservationSummary] = Field(
+        description="Observations belonging to this entity", default_factory=list
     )
 
-    # Related entities
     related_results: Sequence[EntitySummary | RelationSummary | ObservationSummary] = Field(
-        description="related results"
+        description="Related items", default_factory=list
+    )
+
+
+class GraphContext(BaseModel):
+    """Complete context response."""
+
+    # hierarchical results
+    results: Sequence[ContextResult] = Field(
+        description="Hierarchical results with related items nested", default_factory=list
     )
 
     # Context metadata
     metadata: MemoryMetadata
 
-    page: int = 1
-    page_size: int = 1
+    page: Optional[int] = None
+    page_size: Optional[int] = None

basic_memory/schemas/project_info.py

@@ -1,5 +1,6 @@
 """Schema for project info response."""
 
+import os
 from datetime import datetime
 from typing import Dict, List, Optional, Any
 
@@ -75,14 +76,24 @@ 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."""
 
     # Project configuration
     project_name: str = Field(description="Name of the current project")
     project_path: str = Field(description="Path to the current project files")
-    available_projects: Dict[str, str] = Field(
-        description="Map of configured project names to paths"
+    available_projects: Dict[str, Dict[str, Any]] = Field(
+        description="Map of configured project names to detailed project information"
     )
     default_project: str = Field(description="Name of the default project")
 
@@ -94,3 +105,102 @@ class ProjectInfoResponse(BaseModel):
 
     # System status
     system: SystemStatus = Field(description="System and service status information")
+
+
+class ProjectInfoRequest(BaseModel):
+    """Request model for switching projects."""
+
+    name: str = Field(..., description="Name of the project to switch to")
+    path: str = Field(..., description="Path to the project directory")
+    set_default: bool = Field(..., description="Set the project as the default")
+
+
+class WatchEvent(BaseModel):
+    timestamp: datetime
+    path: str
+    action: str  # new, delete, etc
+    status: str  # success, error
+    checksum: Optional[str]
+    error: Optional[str] = None
+
+
+class WatchServiceState(BaseModel):
+    # Service status
+    running: bool = False
+    start_time: datetime = datetime.now()  # Use directly with Pydantic model
+    pid: int = os.getpid()  # Use directly with Pydantic model
+
+    # Stats
+    error_count: int = 0
+    last_error: Optional[datetime] = None
+    last_scan: Optional[datetime] = None
+
+    # File counts
+    synced_files: int = 0
+
+    # Recent activity
+    recent_events: List[WatchEvent] = []  # Use directly with Pydantic model
+
+    def add_event(
+        self,
+        path: str,
+        action: str,
+        status: str,
+        checksum: Optional[str] = None,
+        error: Optional[str] = None,
+    ) -> WatchEvent:  # pragma: no cover
+        event = WatchEvent(
+            timestamp=datetime.now(),
+            path=path,
+            action=action,
+            status=status,
+            checksum=checksum,
+            error=error,
+        )
+        self.recent_events.insert(0, event)
+        self.recent_events = self.recent_events[:100]  # Keep last 100
+        return event
+
+    def record_error(self, error: str):  # pragma: no cover
+        self.error_count += 1
+        self.add_event(path="", action="sync", status="error", error=error)
+        self.last_error = datetime.now()
+
+
+class ProjectWatchStatus(BaseModel):
+    """Project with its watch status."""
+
+    name: str = Field(..., description="Name of the project")
+    path: str = Field(..., description="Path to the project")
+    watch_status: Optional[WatchServiceState] = Field(
+        None, description="Watch status information for the project"
+    )
+
+
+class ProjectItem(BaseModel):
+    """Simple representation of a project."""
+
+    name: str
+    path: str
+    is_default: bool = False
+
+
+class ProjectList(BaseModel):
+    """Response model for listing projects."""
+
+    projects: List[ProjectItem]
+    default_project: str
+
+
+class ProjectStatusResponse(BaseModel):
+    """Response model for switching projects."""
+
+    message: str = Field(..., description="Status message about the project switch")
+    status: str = Field(..., description="Status of the switch (success or error)")
+    default: bool = Field(..., description="True if the project was set as the default")
+    old_project: Optional[ProjectItem] = Field(
+        None, description="Information about the project being switched from"
+    )
+    new_project: Optional[ProjectItem] = Field(
+        None, description="Information about the project being switched to"
+    )

basic_memory/schemas/prompt.py

@@ -0,0 +1,90 @@
+"""Request and response schemas for prompt-related operations."""
+
+from typing import Optional, List, Any, Dict
+from pydantic import BaseModel, Field
+
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import EntitySummary, ObservationSummary, RelationSummary
+
+
+class PromptContextItem(BaseModel):
+    """Container for primary and related results to render in a prompt."""
+
+    primary_results: List[EntitySummary]
+    related_results: List[EntitySummary | ObservationSummary | RelationSummary]
+
+
+class ContinueConversationRequest(BaseModel):
+    """Request for generating a continue conversation prompt.
+
+    Used to provide context for continuing a conversation on a specific topic
+    or with recent activity from a given timeframe.
+    """
+
+    topic: Optional[str] = Field(None, description="Topic or keyword to search for")
+    timeframe: Optional[TimeFrame] = Field(
+        None, description="How far back to look for activity (e.g. '1d', '1 week')"
+    )
+    # Limit depth to max 2 for performance reasons - higher values cause significant slowdown
+    search_items_limit: int = Field(
+        5,
+        description="Maximum number of search results to include in context (max 10)",
+        ge=1,
+        le=10,
+    )
+    depth: int = Field(
+        1,
+        description="How many relationship 'hops' to follow when building context (max 5)",
+        ge=1,
+        le=5,
+    )
+    # Limit related items to prevent overloading the context
+    related_items_limit: int = Field(
+        5, description="Maximum number of related items to include in context (max 10)", ge=1, le=10
+    )
+
+
+class SearchPromptRequest(BaseModel):
+    """Request for generating a search results prompt.
+
+    Used to format search results into a prompt with context and suggestions.
+    """
+
+    query: str = Field(..., description="The search query text")
+    timeframe: Optional[TimeFrame] = Field(
+        None, description="Optional timeframe to limit results (e.g. '1d', '1 week')"
+    )
+
+
+class PromptMetadata(BaseModel):
+    """Metadata about a prompt response.
+
+    Contains statistical information about the prompt generation process
+    and results, useful for debugging and UI display.
+    """
+
+    query: Optional[str] = Field(None, description="The original query or topic")
+    timeframe: Optional[str] = Field(None, description="The timeframe used for filtering")
+    search_count: int = Field(0, description="Number of search results found")
+    context_count: int = Field(0, description="Number of context items retrieved")
+    observation_count: int = Field(0, description="Total number of observations included")
+    relation_count: int = Field(0, description="Total number of relations included")
+    total_items: int = Field(0, description="Total number of all items included in the prompt")
+    search_limit: int = Field(0, description="Maximum search results requested")
+    context_depth: int = Field(0, description="Context depth used")
+    related_limit: int = Field(0, description="Maximum related items requested")
+    generated_at: str = Field(..., description="ISO timestamp when this prompt was generated")
+
+
+class PromptResponse(BaseModel):
+    """Response containing the rendered prompt.
+
+    Includes both the rendered prompt text and the context that was used
+    to render it, for potential client-side use.
+    """
+
+    prompt: str = Field(..., description="The rendered prompt text")
+    context: Dict[str, Any] = Field(..., description="The context used to render the prompt")
+    metadata: PromptMetadata = Field(
+        ..., description="Metadata about the prompt generation process"
+    )

basic_memory/schemas/request.py

@@ -1,9 +1,9 @@
 """Request schemas for interacting with the knowledge graph."""
 
-from typing import List, Optional, Annotated
+from typing import List, Optional, Annotated, Literal
 from annotated_types import MaxLen, MinLen
 
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 
 from basic_memory.schemas.base import (
     Relation,
@@ -56,3 +56,57 @@ class GetEntitiesRequest(BaseModel):
 
 class CreateRelationsRequest(BaseModel):
     relations: List[Relation]
+
+
+class EditEntityRequest(BaseModel):
+    """Request schema for editing an existing entity's content.
+
+    This allows for targeted edits without requiring the full entity content.
+    Supports various operation types for different editing scenarios.
+    """
+
+    operation: Literal["append", "prepend", "find_replace", "replace_section"]
+    content: str
+    section: Optional[str] = None
+    find_text: Optional[str] = None
+    expected_replacements: int = 1
+
+    @field_validator("section")
+    @classmethod
+    def validate_section_for_replace_section(cls, v, info):
+        """Ensure section is provided for replace_section operation."""
+        if info.data.get("operation") == "replace_section" and not v:
+            raise ValueError("section parameter is required for replace_section operation")
+        return v
+
+    @field_validator("find_text")
+    @classmethod
+    def validate_find_text_for_find_replace(cls, v, info):
+        """Ensure find_text is provided for find_replace operation."""
+        if info.data.get("operation") == "find_replace" and not v:
+            raise ValueError("find_text parameter is required for find_replace operation")
+        return v
+
+
+class MoveEntityRequest(BaseModel):
+    """Request schema for moving an entity to a new file location.
+
+    This allows moving notes to different paths while maintaining project
+    consistency and optionally updating permalinks based on configuration.
+    """
+
+    identifier: Annotated[str, MinLen(1), MaxLen(200)]
+    destination_path: Annotated[str, MinLen(1), MaxLen(500)]
+    project: Optional[str] = None
+
+    @field_validator("destination_path")
+    @classmethod
+    def validate_destination_path(cls, v):
+        """Ensure destination path is relative and valid."""
+        if v.startswith("/"):
+            raise ValueError("destination_path must be relative, not absolute")
+        if ".." in v:
+            raise ValueError("destination_path cannot contain '..' path components")
+        if not v.strip():
+            raise ValueError("destination_path cannot be empty or whitespace only")
+        return v.strip()

basic_memory/schemas/search.py

@@ -90,7 +90,7 @@ class SearchResult(BaseModel):
     title: str
     type: SearchItemType
     score: float
-    entity: Optional[Permalink]
+    entity: Optional[Permalink] = None
     permalink: Optional[str]
     content: Optional[str] = None
     file_path: str

basic_memory/services/__init__.py

@@ -3,5 +3,6 @@
 from .service import BaseService
 from .file_service import FileService
 from .entity_service import EntityService
+from .project_service import ProjectService
 
-__all__ = ["BaseService", "FileService", "EntityService"]
+__all__ = ["BaseService", "FileService", "EntityService", "ProjectService"]