basic-memory 0.17.1__py3-none-any.whl

basic_memory/schemas/memory.py

@@ -0,0 +1,285 @@
+"""Schemas for memory context."""
+
+from datetime import datetime
+from typing import List, Optional, Annotated, Sequence, Literal, Union, Dict
+
+from annotated_types import MinLen, MaxLen
+from pydantic import BaseModel, Field, BeforeValidator, TypeAdapter, field_serializer
+
+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
+    """
+    # Empty paths are not valid
+    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 with validation.
+
+    Args:
+        url: A path like "specs/search" or "memory://specs/search"
+
+    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:
+        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://")
+
+    # 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")
+        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),
+]
+
+memory_url = TypeAdapter(MemoryUrl)
+
+
+def memory_url_path(url: memory_url) -> str:  # pyright: ignore
+    """
+    Returns the uri for a url value by removing the prefix "memory://" from a given MemoryUrl.
+
+    This function processes a given MemoryUrl by removing the "memory://"
+    prefix and returns the resulting string. If the provided url does not
+    begin with "memory://", the function will simply return the input url
+    unchanged.
+
+    :param url: A MemoryUrl object representing the URL with a "memory://" prefix.
+    :type url: MemoryUrl
+    :return: A string representing the URL with the "memory://" prefix removed.
+    :rtype: str
+    """
+    return url.removeprefix("memory://")
+
+
+class EntitySummary(BaseModel):
+    """Simplified entity representation."""
+
+    type: Literal["entity"] = "entity"
+    entity_id: int  # Database ID for v2 API consistency
+    permalink: Optional[str]
+    title: str
+    content: Optional[str] = None
+    file_path: str
+    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: Literal["relation"] = "relation"
+    relation_id: int  # Database ID for v2 API consistency
+    entity_id: Optional[int] = None  # ID of the entity this relation belongs to
+    title: str
+    file_path: str
+    permalink: str
+    relation_type: str
+    from_entity: Optional[str] = None
+    from_entity_id: Optional[int] = None  # ID of source entity
+    to_entity: Optional[str] = None
+    to_entity_id: Optional[int] = None  # ID of target entity
+    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: Literal["observation"] = "observation"
+    observation_id: int  # Database ID for v2 API consistency
+    entity_id: Optional[int] = None  # ID of the entity this observation belongs to
+    title: str
+    file_path: str
+    permalink: str
+    category: str
+    content: str
+    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."""
+
+    uri: Optional[str] = None
+    types: Optional[List[SearchItemType]] = None
+    depth: int
+    timeframe: Optional[str] = None
+    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"),
+    ]
+
+    observations: Sequence[ObservationSummary] = Field(
+        description="Observations belonging to this entity", default_factory=list
+    )
+
+    related_results: Sequence[
+        Annotated[
+            Union[EntitySummary, RelationSummary, ObservationSummary], Field(discriminator="type")
+        ]
+    ] = Field(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: 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

@@ -0,0 +1,212 @@
+"""Schema for project info response."""
+
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+
+from pydantic import Field, BaseModel
+
+from basic_memory.utils import generate_permalink
+
+
+class ProjectStatistics(BaseModel):
+    """Statistics about the current project."""
+
+    # Basic counts
+    total_entities: int = Field(description="Total number of entities in the knowledge base")
+    total_observations: int = Field(description="Total number of observations across all entities")
+    total_relations: int = Field(description="Total number of relations between entities")
+    total_unresolved_relations: int = Field(
+        description="Number of relations with unresolved targets"
+    )
+
+    # Entity counts by type
+    entity_types: Dict[str, int] = Field(
+        description="Count of entities by type (e.g., note, conversation)"
+    )
+
+    # Observation counts by category
+    observation_categories: Dict[str, int] = Field(
+        description="Count of observations by category (e.g., tech, decision)"
+    )
+
+    # Relation counts by type
+    relation_types: Dict[str, int] = Field(
+        description="Count of relations by type (e.g., implements, relates_to)"
+    )
+
+    # Graph metrics
+    most_connected_entities: List[Dict[str, Any]] = Field(
+        description="Entities with the most relations, including their titles and permalinks"
+    )
+    isolated_entities: int = Field(description="Number of entities with no relations")
+
+
+class ActivityMetrics(BaseModel):
+    """Activity metrics for the current project."""
+
+    # Recent activity
+    recently_created: List[Dict[str, Any]] = Field(
+        description="Recently created entities with timestamps"
+    )
+    recently_updated: List[Dict[str, Any]] = Field(
+        description="Recently updated entities with timestamps"
+    )
+
+    # Growth over time (last 6 months)
+    monthly_growth: Dict[str, Dict[str, int]] = Field(
+        description="Monthly growth statistics for entities, observations, and relations"
+    )
+
+
+class SystemStatus(BaseModel):
+    """System status information."""
+
+    # Version information
+    version: str = Field(description="Basic Memory version")
+
+    # Database status
+    database_path: str = Field(description="Path to the SQLite database")
+    database_size: str = Field(description="Size of the database in human-readable format")
+
+    # Watch service status
+    watch_status: Optional[Dict[str, Any]] = Field(
+        default=None, description="Watch service status information (if running)"
+    )
+
+    # System information
+    timestamp: datetime = Field(description="Timestamp when the information was collected")
+
+
+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, Dict[str, Any]] = Field(
+        description="Map of configured project names to detailed project information"
+    )
+    default_project: str = Field(description="Name of the default project")
+
+    # Statistics
+    statistics: ProjectStatistics = Field(description="Statistics about the knowledge base")
+
+    # Activity metrics
+    activity: ActivityMetrics = Field(description="Activity and growth metrics")
+
+    # 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."""
+
+    id: int
+    name: str
+    path: str
+    is_default: bool = False
+
+    @property
+    def permalink(self) -> str:  # pragma: no cover
+        return generate_permalink(self.name)
+
+    @property
+    def home(self) -> Path:  # pragma: no cover
+        return Path(self.path).expanduser()
+
+    @property
+    def project_url(self) -> str:  # pragma: no cover
+        return f"/{generate_permalink(self.name)}"
+
+
+class ProjectList(BaseModel):
+    """Response model for listing projects."""
+
+    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

@@ -0,0 +1,112 @@
+"""Request schemas for interacting with the knowledge graph."""
+
+from typing import List, Optional, Annotated, Literal
+from annotated_types import MaxLen, MinLen
+
+from pydantic import BaseModel, field_validator
+
+from basic_memory.schemas.base import (
+    Relation,
+    Permalink,
+)
+
+
+class SearchNodesRequest(BaseModel):
+    """Search for entities in the knowledge graph.
+
+    The search looks across multiple fields:
+    - Entity title
+    - Entity types
+    - summary
+    - file content
+    - Observations
+
+    Features:
+    - Case-insensitive matching
+    - Partial word matches
+    - Returns full entity objects with relations
+    - Includes all matching entities
+    - If a category is specified, only entities with that category are returned
+
+    Example Queries:
+    - "memory" - Find entities related to memory systems
+    - "SQLite" - Find database-related components
+    - "test" - Find test-related entities
+    - "implementation" - Find concrete implementations
+    - "service" - Find service components
+
+    Note: Currently uses SQL ILIKE for matching. Wildcard (*) searches
+    and full-text search capabilities are planned for future versions.
+    """
+
+    query: Annotated[str, MinLen(1), MaxLen(200)]
+    category: Optional[str] = None
+
+
+class GetEntitiesRequest(BaseModel):
+    """Retrieve specific entities by their IDs.
+
+    Used to load complete entity details including all observations
+    and relations. Particularly useful for following relations
+    discovered through search.
+    """
+
+    permalinks: Annotated[List[Permalink], MinLen(1), MaxLen(10)]
+
+
+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()