basic-memory 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

basic_memory/schemas/memory.py

@@ -64,6 +64,7 @@ class EntitySummary(BaseModel):
     type: str = "entity"
     permalink: Optional[str]
     title: str
+    content: Optional[str] = None
     file_path: str
     created_at: datetime
 
@@ -76,8 +77,8 @@ class RelationSummary(BaseModel):
     file_path: str
     permalink: str
     relation_type: str
-    from_id: str
-    to_id: Optional[str] = None
+    from_entity: str
+    to_entity: Optional[str] = None
     created_at: datetime
 
 

basic_memory/schemas/project_info.py

@@ -0,0 +1,96 @@
+"""Schema for project info response."""
+
+from datetime import datetime
+from typing import Dict, List, Optional, Any
+
+from pydantic import Field, BaseModel
+
+
+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, str] = Field(
+        description="Map of configured project names to paths"
+    )
+    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")

basic_memory/schemas/search.py

@@ -11,6 +11,8 @@ from datetime import datetime
 from enum import Enum
 from pydantic import BaseModel, field_validator
 
+from basic_memory.schemas.base import Permalink
+
 
 class SearchItemType(str, Enum):
     """Types of searchable items."""
@@ -26,18 +28,24 @@ class SearchQuery(BaseModel):
     Use ONE of these primary search modes:
     - permalink: Exact permalink match
     - permalink_match: Path pattern with *
-    - text: Full-text search of title/content
+    - text: Full-text search of title/content (supports boolean operators: AND, OR, NOT)
 
     Optionally filter results by:
     - types: Limit to specific item types
     - entity_types: Limit to specific entity types
     - after_date: Only items after date
+
+    Boolean search examples:
+    - "python AND flask" - Find items with both terms
+    - "python OR django" - Find items with either term
+    - "python NOT django" - Find items with python but not django
+    - "(python OR flask) AND web" - Use parentheses for grouping
     """
 
     # Primary search modes (use ONE of these)
     permalink: Optional[str] = None  # Exact permalink match
-    permalink_match: Optional[str] = None  # Exact permalink match
-    text: Optional[str] = None  # Full-text search
+    permalink_match: Optional[str] = None  # Glob permalink match
+    text: Optional[str] = None  # Full-text search (now supports boolean operators)
     title: Optional[str] = None  # title only search
 
     # Optional filters
@@ -57,61 +65,48 @@ class SearchQuery(BaseModel):
         return (
             self.permalink is None
             and self.permalink_match is None
+            and self.title is None
             and self.text is None
             and self.after_date is None
             and self.types is None
             and self.entity_types is None
         )
 
+    def has_boolean_operators(self) -> bool:
+        """Check if the text query contains boolean operators (AND, OR, NOT)."""
+        if not self.text:  # pragma: no cover
+            return False
+
+        # Check for common boolean operators with correct word boundaries
+        # to avoid matching substrings like "GRAND" containing "AND"
+        boolean_patterns = [" AND ", " OR ", " NOT ", "(", ")"]
+        text = f" {self.text} "  # Add spaces to ensure we match word boundaries
+        return any(pattern in text for pattern in boolean_patterns)
+
 
 class SearchResult(BaseModel):
     """Search result with score and metadata."""
 
-    id: int
     title: str
     type: SearchItemType
     score: float
+    entity: Optional[Permalink]
     permalink: Optional[str]
+    content: Optional[str] = None
     file_path: str
 
     metadata: Optional[dict] = None
 
     # Type-specific fields
-    entity_id: Optional[int] = None  # For observations
     category: Optional[str] = None  # For observations
-    from_id: Optional[int] = None  # For relations
-    to_id: Optional[int] = None  # For relations
+    from_entity: Optional[Permalink] = None  # For relations
+    to_entity: Optional[Permalink] = None  # For relations
     relation_type: Optional[str] = None  # For relations
 
 
-class RelatedResult(BaseModel):
-    type: SearchItemType
-    id: int
-    title: str
-    permalink: str
-    depth: int
-    root_id: int
-    created_at: datetime
-    from_id: Optional[int] = None
-    to_id: Optional[int] = None
-    relation_type: Optional[str] = None
-    category: Optional[str] = None
-    entity_id: Optional[int] = None
-
-
 class SearchResponse(BaseModel):
     """Wrapper for search results."""
 
     results: List[SearchResult]
     current_page: int
     page_size: int
-
-
-# Schema for future advanced search endpoint
-class AdvancedSearchQuery(BaseModel):
-    """Advanced full-text search with explicit FTS5 syntax."""
-
-    query: str  # Raw FTS5 query (e.g., "foo AND bar")
-    types: Optional[List[SearchItemType]] = None
-    entity_types: Optional[List[str]] = None
-    after_date: Optional[Union[datetime, str]] = None

basic_memory/services/context_service.py

@@ -165,7 +165,7 @@ class ContextService:
                 from_id,
                 to_id,
                 relation_type,
-                content,
+                content_snippet as content,
                 category,
                 entity_id,
                 0 as depth,
@@ -189,7 +189,7 @@ class ContextService:
                 r.from_id,
                 r.to_id,
                 r.relation_type,
-                r.content,
+                r.content_snippet as content,
                 r.category,
                 r.entity_id,
                 cg.depth + 1,
@@ -218,7 +218,7 @@ class ContextService:
                 e.from_id,
                 e.to_id,
                 e.relation_type,
-                e.content,
+                e.content_snippet as content,
                 e.category,
                 e.entity_id,
                 cg.depth + 1,  -- Increment depth for entities

basic_memory/services/entity_service.py

@@ -144,7 +144,7 @@ class EntityService(BaseService[EntityModel]):
         post = await schema_to_markdown(schema)
 
         # write file
-        final_content = frontmatter.dumps(post)
+        final_content = frontmatter.dumps(post, sort_keys=False)
         checksum = await self.file_service.write_file(file_path, final_content)
 
         # parse entity from file
@@ -171,7 +171,13 @@ class EntityService(BaseService[EntityModel]):
                 entity = await self.get_by_permalink(permalink_or_id)
             else:
                 entities = await self.get_entities_by_id([permalink_or_id])
-                assert len(entities) == 1, f"Expected 1 entity, got {len(entities)}"
+                if len(entities) != 1:  # pragma: no cover
+                    logger.error(
+                        "Entity lookup error", entity_id=permalink_or_id, found_count=len(entities)
+                    )
+                    raise ValueError(
+                        f"Expected 1 entity with ID {permalink_or_id}, got {len(entities)}"
+                    )
                 entity = entities[0]
 
             # Delete file first

basic_memory/services/file_service.py

@@ -3,9 +3,7 @@
 import mimetypes
 from os import stat_result
 from pathlib import Path
-from typing import Tuple, Union, Dict, Any
-
-from loguru import logger
+from typing import Any, Dict, Tuple, Union
 
 from basic_memory import file_utils
 from basic_memory.file_utils import FileError
@@ -13,6 +11,8 @@ from basic_memory.markdown.markdown_processor import MarkdownProcessor
 from basic_memory.models import Entity as EntityModel
 from basic_memory.schemas import Entity as EntitySchema
 from basic_memory.services.exceptions import FileOperationError
+from basic_memory.utils import FilePath
+from loguru import logger
 
 
 class FileService:
@@ -60,7 +60,7 @@ class FileService:
         Returns:
             Raw content string without metadata sections
         """
-        logger.debug(f"Reading entity with permalink: {entity.permalink}")
+        logger.debug("Reading entity content", entity_id=entity.id, permalink=entity.permalink)
 
         file_path = self.get_entity_path(entity)
         markdown = await self.markdown_processor.read_file(file_path)
@@ -78,13 +78,13 @@ class FileService:
         path = self.get_entity_path(entity)
         await self.delete_file(path)
 
-    async def exists(self, path: Union[Path, str]) -> bool:
+    async def exists(self, path: FilePath) -> bool:
         """Check if file exists at the provided path.
 
         If path is relative, it is assumed to be relative to base_path.
 
         Args:
-            path: Path to check (Path object or string)
+            path: Path to check (Path or string)
 
         Returns:
             True if file exists, False otherwise
@@ -93,23 +93,25 @@ class FileService:
             FileOperationError: If check fails
         """
         try:
-            path = Path(path)
-            if path.is_absolute():
-                return path.exists()
+            # Convert string to Path if needed
+            path_obj = Path(path) if isinstance(path, str) else path
+
+            if path_obj.is_absolute():
+                return path_obj.exists()
             else:
-                return (self.base_path / path).exists()
+                return (self.base_path / path_obj).exists()
         except Exception as e:
-            logger.error(f"Failed to check file existence {path}: {e}")
+            logger.error("Failed to check file existence", path=str(path), error=str(e))
             raise FileOperationError(f"Failed to check file existence: {e}")
 
-    async def write_file(self, path: Union[Path, str], content: str) -> str:
+    async def write_file(self, path: FilePath, content: str) -> str:
         """Write content to file and return checksum.
 
         Handles both absolute and relative paths. Relative paths are resolved
         against base_path.
 
         Args:
-            path: Where to write (Path object or string)
+            path: Where to write (Path or string)
             content: Content to write
 
         Returns:
@@ -118,34 +120,43 @@ class FileService:
         Raises:
             FileOperationError: If write fails
         """
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
 
         try:
             # Ensure parent directory exists
             await file_utils.ensure_directory(full_path.parent)
 
             # Write content atomically
+            logger.info(
+                "Writing file",
+                operation="write_file",
+                path=str(full_path),
+                content_length=len(content),
+                is_markdown=full_path.suffix.lower() == ".md",
+            )
+
             await file_utils.write_file_atomic(full_path, content)
 
             # Compute and return checksum
             checksum = await file_utils.compute_checksum(content)
-            logger.debug(f"wrote file: {full_path}, checksum: {checksum}")
+            logger.debug("File write completed", path=str(full_path), checksum=checksum)
             return checksum
 
         except Exception as e:
-            logger.error(f"Failed to write file {full_path}: {e}")
+            logger.exception("File write error", path=str(full_path), error=str(e))
             raise FileOperationError(f"Failed to write file: {e}")
 
     # TODO remove read_file
-    async def read_file(self, path: Union[Path, str]) -> Tuple[str, str]:
+    async def read_file(self, path: FilePath) -> Tuple[str, str]:
         """Read file and compute checksum.
 
         Handles both absolute and relative paths. Relative paths are resolved
         against base_path.
 
         Args:
-            path: Path to read (Path object or string)
+            path: Path to read (Path or string)
 
         Returns:
             Tuple of (content, checksum)
@@ -153,77 +164,113 @@ class FileService:
         Raises:
             FileOperationError: If read fails
         """
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
 
         try:
-            content = full_path.read_text()
+            logger.debug("Reading file", operation="read_file", path=str(full_path))
+            content = full_path.read_text(encoding="utf-8")
             checksum = await file_utils.compute_checksum(content)
-            logger.debug(f"read file: {full_path}, checksum: {checksum}")
+
+            logger.debug(
+                "File read completed",
+                path=str(full_path),
+                checksum=checksum,
+                content_length=len(content),
+            )
             return content, checksum
 
         except Exception as e:
-            logger.error(f"Failed to read file {full_path}: {e}")
+            logger.exception("File read error", path=str(full_path), error=str(e))
             raise FileOperationError(f"Failed to read file: {e}")
 
-    async def delete_file(self, path: Union[Path, str]) -> None:
+    async def delete_file(self, path: FilePath) -> None:
         """Delete file if it exists.
 
         Handles both absolute and relative paths. Relative paths are resolved
         against base_path.
 
         Args:
-            path: Path to delete (Path object or string)
+            path: Path to delete (Path or string)
         """
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
         full_path.unlink(missing_ok=True)
 
-    async def update_frontmatter(self, path: Union[Path, str], updates: Dict[str, Any]) -> str:
+    async def update_frontmatter(self, path: FilePath, updates: Dict[str, Any]) -> str:
         """
         Update frontmatter fields in a file while preserving all content.
-        """
 
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        Args:
+            path: Path to the file (Path or string)
+            updates: Dictionary of frontmatter fields to update
+
+        Returns:
+            Checksum of updated file
+        """
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
         return await file_utils.update_frontmatter(full_path, updates)
 
-    async def compute_checksum(self, path: Union[str, Path]) -> str:
-        """Compute checksum for a file."""
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+    async def compute_checksum(self, path: FilePath) -> str:
+        """Compute checksum for a file.
+
+        Args:
+            path: Path to the file (Path or string)
+
+        Returns:
+            Checksum of the file content
+
+        Raises:
+            FileError: If checksum computation fails
+        """
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
+
         try:
             if self.is_markdown(path):
                 # read str
-                content = full_path.read_text()
+                content = full_path.read_text(encoding="utf-8")
             else:
                 # read bytes
                 content = full_path.read_bytes()
             return await file_utils.compute_checksum(content)
 
         except Exception as e:  # pragma: no cover
-            logger.error(f"Failed to compute checksum for {path}: {e}")
+            logger.error("Failed to compute checksum", path=str(full_path), error=str(e))
             raise FileError(f"Failed to compute checksum for {path}: {e}")
 
-    def file_stats(self, path: Union[Path, str]) -> stat_result:
-        """
-        Return file stats for a given path.
-        :param path:
-        :return:
+    def file_stats(self, path: FilePath) -> stat_result:
+        """Return file stats for a given path.
+
+        Args:
+            path: Path to the file (Path or string)
+
+        Returns:
+            File statistics
         """
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
         # get file timestamps
         return full_path.stat()
 
-    def content_type(self, path: Union[Path, str]) -> str:
-        """
-        Return content_type for a given path.
-        :param path:
-        :return:
+    def content_type(self, path: FilePath) -> str:
+        """Return content_type for a given path.
+
+        Args:
+            path: Path to the file (Path or string)
+
+        Returns:
+            MIME type of the file
         """
-        path = Path(path)
-        full_path = path if path.is_absolute() else self.base_path / path
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        full_path = path_obj if path_obj.is_absolute() else self.base_path / path_obj
         # get file timestamps
         mime_type, _ = mimetypes.guess_type(full_path.name)
 
@@ -234,10 +281,13 @@ class FileService:
         content_type = mime_type or "text/plain"
         return content_type
 
-    def is_markdown(self, path: Union[Path, str]) -> bool:
-        """
-        Return content_type for a given path.
-        :param path:
-        :return:
+    def is_markdown(self, path: FilePath) -> bool:
+        """Check if a file is a markdown file.
+
+        Args:
+            path: Path to the file (Path or string)
+
+        Returns:
+            True if the file is a markdown file, False otherwise
         """
         return self.content_type(path) == "text/markdown"

basic_memory/services/link_resolver.py

@@ -1,12 +1,11 @@
 """Service for resolving markdown links to permalinks."""
 
-from typing import Optional, Tuple, List
+from typing import Optional, Tuple
 
 from loguru import logger
 
 from basic_memory.models import Entity
 from basic_memory.repository.entity_repository import EntityRepository
-from basic_memory.repository.search_repository import SearchIndexRow
 from basic_memory.schemas.search import SearchQuery, SearchItemType
 from basic_memory.services.search_service import SearchService
 
@@ -41,8 +40,9 @@ class LinkResolver:
             return entity
 
         # 2. Try exact title match
-        entity = await self.entity_repository.get_by_title(clean_text)
-        if entity:
+        found = await self.entity_repository.get_by_title(clean_text)
+        if found and len(found) == 1:
+            entity = found[0]
             logger.debug(f"Found title match: {entity.title}")
             return entity
 
@@ -54,7 +54,7 @@ class LinkResolver:
 
             if results:
                 # Look for best match
-                best_match = self._select_best_match(clean_text, results)
+                best_match = min(results, key=lambda x: x.score)  # pyright: ignore
                 logger.debug(
                     f"Selected best match from {len(results)} results: {best_match.permalink}"
                 )
@@ -88,43 +88,3 @@ class LinkResolver:
             alias = alias.strip()
 
         return text, alias
-
-    def _select_best_match(self, search_text: str, results: List[SearchIndexRow]) -> SearchIndexRow:
-        """Select best match from search results.
-
-        Uses multiple criteria:
-        1. Word matches in title field
-        2. Word matches in path
-        3. Overall search score
-        """
-        # Get search terms for matching
-        terms = search_text.lower().split()
-
-        # Score each result
-        scored_results = []
-        for result in results:
-            # Start with base score (lower is better)
-            score = result.score or 0
-
-            if result.permalink:
-                # Parse path components
-                path_parts = result.permalink.lower().split("/")
-                last_part = path_parts[-1] if path_parts else ""
-            else:
-                last_part = ""  # pragma: no cover
-
-            # Title word match boosts
-            term_matches = [term for term in terms if term in last_part]
-            if term_matches:
-                score *= 0.5  # Boost for each matching term
-
-            # Exact title match is best
-            if last_part == search_text.lower():
-                score *= 0.2
-
-            scored_results.append((score, result))
-
-        # Sort by score (lowest first) and return best
-        scored_results.sort(key=lambda x: x[0], reverse=True)
-
-        return scored_results[0][1]