basic-memory 0.11.0__py3-none-any.whl → 0.12.1__py3-none-any.whl

basic_memory/mcp/tools/search.py

@@ -1,17 +1,27 @@
 """Search tools for Basic Memory MCP server."""
 
+from typing import List, Optional
+
 from loguru import logger
 
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_post
-from basic_memory.schemas.search import SearchQuery, SearchResponse
-from basic_memory.mcp.async_client import client
+from basic_memory.schemas.search import SearchItemType, SearchQuery, SearchResponse
 
 
 @mcp.tool(
     description="Search across all content in the knowledge base.",
 )
-async def search_notes(query: SearchQuery, page: int = 1, page_size: int = 10) -> SearchResponse:
+async def search_notes(
+    query: str,
+    page: int = 1,
+    page_size: int = 10,
+    search_type: str = "text",
+    types: Optional[List[str]] = None,
+    entity_types: Optional[List[str]] = None,
+    after_date: Optional[str] = None,
+) -> SearchResponse:
     """Search across all content in the knowledge base.
 
     This tool searches the knowledge base using full-text search, pattern matching,
@@ -19,59 +29,85 @@ async def search_notes(query: SearchQuery, page: int = 1, page_size: int = 10) -
     and date.
 
     Args:
-        query: SearchQuery object with search parameters including:
-            - text: Full-text search (e.g., "project planning")
-              Supports boolean operators: AND, OR, NOT and parentheses for grouping
-            - title: Search only in titles (e.g., "Meeting notes")
-            - permalink: Exact permalink match (e.g., "docs/meeting-notes")
-            - permalink_match: Pattern matching for permalinks (e.g., "docs/*-notes")
-            - types: Optional list of content types to search (e.g., ["entity", "observation"])
-            - entity_types: Optional list of entity types to filter by (e.g., ["note", "person"])
-            - after_date: Optional date filter for recent content (e.g., "1 week", "2d")
+        query: The search query string
         page: The page number of results to return (default 1)
         page_size: The number of results to return per page (default 10)
+        search_type: Type of search to perform, one of: "text", "title", "permalink" (default: "text")
+        types: Optional list of note types to search (e.g., ["note", "person"])
+        entity_types: Optional list of entity types to filter by (e.g., ["entity", "observation"])
+        after_date: Optional date filter for recent content (e.g., "1 week", "2d")
 
     Returns:
         SearchResponse with results and pagination info
 
     Examples:
         # Basic text search
-        results = await search_notes(SearchQuery(text="project planning"))
+        results = await search_notes("project planning")
 
         # Boolean AND search (both terms must be present)
-        results = await search_notes(SearchQuery(text="project AND planning"))
+        results = await search_notes("project AND planning")
 
         # Boolean OR search (either term can be present)
-        results = await search_notes(SearchQuery(text="project OR meeting"))
+        results = await search_notes("project OR meeting")
 
         # Boolean NOT search (exclude terms)
-        results = await search_notes(SearchQuery(text="project NOT meeting"))
+        results = await search_notes("project NOT meeting")
 
         # Boolean search with grouping
-        results = await search_notes(SearchQuery(text="(project OR planning) AND notes"))
+        results = await search_notes("(project OR planning) AND notes")
 
         # Search with type filter
-        results = await search_notes(SearchQuery(
-            text="meeting notes",
+        results = await search_notes(
+            query="meeting notes",
+            types=["entity"],
+        )
+
+        # Search with entity type filter, e.g., note vs
+        results = await search_notes(
+            query="meeting notes",
             types=["entity"],
-        ))
+        )
 
         # Search for recent content
-        results = await search_notes(SearchQuery(
-            text="bug report",
+        results = await search_notes(
+            query="bug report",
             after_date="1 week"
-        ))
+        )
 
         # Pattern matching on permalinks
-        results = await search_notes(SearchQuery(
-            permalink_match="docs/meeting-*"
-        ))
+        results = await search_notes(
+            query="docs/meeting-*",
+            search_type="permalink"
+        )
     """
-    logger.info(f"Searching for {query}")
+    # Create a SearchQuery object based on the parameters
+    search_query = SearchQuery()
+
+    # Set the appropriate search field based on search_type
+    if search_type == "text":
+        search_query.text = query
+    elif search_type == "title":
+        search_query.title = query
+    elif search_type == "permalink" and "*" in query:
+        search_query.permalink_match = query
+    elif search_type == "permalink":
+        search_query.permalink = query
+    else:
+        search_query.text = query  # Default to text search
+
+    # Add optional filters if provided
+    if entity_types:
+        search_query.entity_types = [SearchItemType(t) for t in entity_types]
+    if types:
+        search_query.types = types
+    if after_date:
+        search_query.after_date = after_date
+
+    logger.info(f"Searching for {search_query}")
     response = await call_post(
         client,
         "/search/",
-        json=query.model_dump(),
+        json=search_query.model_dump(),
         params={"page": page, "page_size": page_size},
     )
     return SearchResponse.model_validate(response.json())

basic_memory/mcp/tools/write_note.py

@@ -88,8 +88,10 @@ async def write_note(
     # Format semantic summary based on status code
     action = "Created" if response.status_code == 201 else "Updated"
     summary = [
-        f"# {action} {result.file_path} ({result.checksum[:8] if result.checksum else 'unknown'})",
+        f"# {action} note",
+        f"file_path: {result.file_path}",
         f"permalink: {result.permalink}",
+        f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
     ]
 
     # Count observations by category

basic_memory/repository/repository.py

@@ -137,8 +137,6 @@ class Repository[T: Base]:
 
     async def find_one(self, query: Select[tuple[T]]) -> Optional[T]:
         """Execute a query and retrieve a single record."""
-        logger.debug(f"Finding one {self.Model.__name__} with query: {query}")
-
         # add in load options
         query = query.options(*self.get_load_options())
         result = await self.execute_query(query)
@@ -270,11 +268,9 @@ class Repository[T: Base]:
         """Execute a query asynchronously."""
 
         query = query.options(*self.get_load_options()) if use_query_options else query
-
         logger.debug(f"Executing query: {query}")
         async with db.scoped_session(self.session_maker) as session:
             result = await session.execute(query)
-            logger.debug("Query executed successfully")
             return result
 
     def get_load_options(self) -> List[LoaderOption]:

basic_memory/repository/search_repository.py

@@ -4,10 +4,10 @@ import json
 import time
 from dataclasses import dataclass
 from datetime import datetime
-from typing import List, Optional, Any, Dict
+from typing import Any, Dict, List, Optional
 
 from loguru import logger
-from sqlalchemy import text, Executable, Result
+from sqlalchemy import Executable, Result, text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from basic_memory import db
@@ -123,9 +123,9 @@ class SearchRepository:
         permalink: Optional[str] = None,
         permalink_match: Optional[str] = None,
         title: Optional[str] = None,
-        types: Optional[List[SearchItemType]] = None,
+        types: Optional[List[str]] = None,
         after_date: Optional[datetime] = None,
-        entity_types: Optional[List[str]] = None,
+        entity_types: Optional[List[SearchItemType]] = None,
         limit: int = 10,
         offset: int = 0,
     ) -> List[SearchIndexRow]:
@@ -174,15 +174,15 @@ class SearchRepository:
             else:
                 conditions.append("permalink MATCH :permalink")
 
-        # Handle type filter
-        if types:
-            type_list = ", ".join(f"'{t.value}'" for t in types)
-            conditions.append(f"type IN ({type_list})")
-
         # Handle entity type filter
         if entity_types:
-            entity_type_list = ", ".join(f"'{t}'" for t in entity_types)
-            conditions.append(f"json_extract(metadata, '$.entity_type') IN ({entity_type_list})")
+            type_list = ", ".join(f"'{t.value}'" for t in entity_types)
+            conditions.append(f"type IN ({type_list})")
+
+        # Handle type filter
+        if types:
+            type_list = ", ".join(f"'{t}'" for t in types)
+            conditions.append(f"json_extract(metadata, '$.entity_type') IN ({type_list})")
 
         # Handle date filter using datetime() for proper comparison
         if after_date:

basic_memory/schemas/search.py

@@ -49,8 +49,8 @@ class SearchQuery(BaseModel):
     title: Optional[str] = None  # title only search
 
     # Optional filters
-    types: Optional[List[SearchItemType]] = None  # Filter by item type
-    entity_types: Optional[List[str]] = None  # Filter by entity type
+    types: Optional[List[str]] = None  # Filter by type
+    entity_types: Optional[List[SearchItemType]] = None  # Filter by entity type
     after_date: Optional[Union[datetime, str]] = None  # Time-based filter
 
     @field_validator("after_date")

basic_memory/services/context_service.py

@@ -81,7 +81,7 @@ class ContextService:
         else:
             logger.debug(f"Build context for '{types}'")
             primary = await self.search_repository.search(
-                types=types, after_date=since, limit=limit, offset=offset
+                entity_types=types, after_date=since, limit=limit, offset=offset
             )
 
         # Get type_id pairs for traversal

basic_memory/services/entity_service.py

@@ -1,24 +1,24 @@
 """Service for managing entities in the database."""
 
 from pathlib import Path
-from typing import Sequence, List, Optional, Tuple, Union
+from typing import List, Optional, Sequence, Tuple, Union
 
 import frontmatter
 from loguru import logger
 from sqlalchemy.exc import IntegrityError
 
 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
-from basic_memory.models import Entity as EntityModel, Observation, Relation
+from basic_memory.models import Entity as EntityModel
+from basic_memory.models import Observation, Relation
 from basic_memory.repository import ObservationRepository, RelationRepository
 from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.schemas import Entity as EntitySchema
 from basic_memory.schemas.base import Permalink
-from basic_memory.services.exceptions import EntityNotFoundError, EntityCreationError
-from basic_memory.services import FileService
-from basic_memory.services import BaseService
+from basic_memory.services import BaseService, FileService
+from basic_memory.services.exceptions import EntityCreationError, EntityNotFoundError
 from basic_memory.services.link_resolver import LinkResolver
-from basic_memory.markdown.entity_parser import EntityParser
 from basic_memory.utils import generate_permalink
 
 
@@ -89,7 +89,7 @@ class EntityService(BaseService[EntityModel]):
         logger.debug(f"Creating or updating entity: {schema}")
 
         # Try to find existing entity using smart resolution
-        existing = await self.link_resolver.resolve_link(schema.permalink)
+        existing = await self.link_resolver.resolve_link(schema.permalink or schema.file_path)
 
         if existing:
             logger.debug(f"Found existing entity: {existing.permalink}")
@@ -100,7 +100,7 @@ class EntityService(BaseService[EntityModel]):
 
     async def create_entity(self, schema: EntitySchema) -> EntityModel:
         """Create a new entity and write to filesystem."""
-        logger.debug(f"Creating entity: {schema.permalink}")
+        logger.debug(f"Creating entity: {schema.title}")
 
         # Get file path and ensure it's a Path object
         file_path = Path(schema.file_path)
@@ -230,7 +230,7 @@ class EntityService(BaseService[EntityModel]):
         Creates the entity with null checksum to indicate sync not complete.
         Relations will be added in second pass.
         """
-        logger.debug(f"Creating entity: {markdown.frontmatter.title}")
+        logger.debug(f"Creating entity: {markdown.frontmatter.title} file_path: {file_path}")
         model = entity_model_from_markdown(file_path, markdown)
 
         # Mark as incomplete because we still need to add relations
@@ -315,7 +315,7 @@ class EntityService(BaseService[EntityModel]):
             except IntegrityError:
                 # Unique constraint violation - relation already exists
                 logger.debug(
-                    f"Skipping duplicate relation {rel.type} from {db_entity.permalink} target: {rel.target}, type: {rel.type}"
+                    f"Skipping duplicate relation {rel.type} from {db_entity.permalink} target: {rel.target}"
                 )
                 continue
 

basic_memory/services/file_service.py

@@ -60,7 +60,7 @@ class FileService:
         Returns:
             Raw content string without metadata sections
         """
-        logger.debug("Reading entity content", entity_id=entity.id, permalink=entity.permalink)
+        logger.debug(f"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)

basic_memory/services/initialization.py

@@ -0,0 +1,143 @@
+"""Shared initialization service for Basic Memory.
+
+This module provides shared initialization functions used by both CLI and API
+to ensure consistent application startup across all entry points.
+"""
+
+import asyncio
+from typing import Optional
+
+from loguru import logger
+
+from basic_memory import db
+from basic_memory.config import ProjectConfig, config_manager
+from basic_memory.sync import WatchService
+
+# Import this inside functions to avoid circular imports
+# from basic_memory.cli.commands.sync import get_sync_service
+
+
+async def initialize_database(app_config: ProjectConfig) -> None:
+    """Run database migrations to ensure schema is up to date.
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    try:
+        logger.info("Running database migrations...")
+        await db.run_migrations(app_config)
+        logger.info("Migrations completed successfully")
+    except Exception as e:
+        logger.error(f"Error running migrations: {e}")
+        # Allow application to continue - it might still work
+        # depending on what the error was, and will fail with a
+        # more specific error if the database is actually unusable
+
+
+async def initialize_file_sync(
+    app_config: ProjectConfig,
+) -> asyncio.Task:
+    """Initialize file synchronization services.
+
+    Args:
+        app_config: The Basic Memory project configuration
+
+    Returns:
+        Tuple of (sync_service, watch_service, watch_task) if sync is enabled,
+        or (None, None, None) if sync is disabled
+    """
+    # Load app configuration
+    # Import here to avoid circular imports
+    from basic_memory.cli.commands.sync import get_sync_service
+
+    # Initialize sync service
+    sync_service = await get_sync_service()
+
+    # Initialize watch service
+    watch_service = WatchService(
+        sync_service=sync_service,
+        file_service=sync_service.entity_service.file_service,
+        config=app_config,
+        quiet=True,
+    )
+
+    # Create the background task for running sync
+    async def run_background_sync():  # pragma: no cover
+        # Run initial full sync
+        await sync_service.sync(app_config.home)
+        logger.info("Sync completed successfully")
+
+        # Start background sync task
+        logger.info(f"Starting watch service to sync file changes in dir: {app_config.home}")
+
+        # Start watching for changes
+        await watch_service.run()
+
+    watch_task = asyncio.create_task(run_background_sync())
+    logger.info("Watch service started")
+    return watch_task
+
+
+async def initialize_app(
+    app_config: ProjectConfig,
+) -> Optional[asyncio.Task]:
+    """Initialize the Basic Memory application.
+
+    This function handles all initialization steps needed for both API and shor lived CLI commands.
+    For long running commands like mcp, a
+    - Running database migrations
+    - Setting up file synchronization
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    # Initialize database first
+    await initialize_database(app_config)
+
+    basic_memory_config = config_manager.load_config()
+    logger.info(f"Sync changes enabled: {basic_memory_config.sync_changes}")
+    logger.info(
+        f"Update permalinks on move enabled: {basic_memory_config.update_permalinks_on_move}"
+    )
+    if not basic_memory_config.sync_changes:  # pragma: no cover
+        logger.info("Sync changes disabled. Skipping watch service.")
+        return
+
+    # Initialize file sync services
+    return await initialize_file_sync(app_config)
+
+
+def ensure_initialization(app_config: ProjectConfig) -> None:
+    """Ensure initialization runs in a synchronous context.
+
+    This is a wrapper for the async initialize_app function that can be
+    called from synchronous code like CLI entry points.
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    try:
+        asyncio.run(initialize_app(app_config))
+    except Exception as e:
+        logger.error(f"Error during initialization: {e}")
+        # Continue execution even if initialization fails
+        # The command might still work, or will fail with a
+        # more specific error message
+
+
+def ensure_initialize_database(app_config: ProjectConfig) -> None:
+    """Ensure initialization runs in a synchronous context.
+
+    This is a wrapper for the async initialize_database function that can be
+    called from synchronous code like CLI entry points.
+
+    Args:
+        app_config: The Basic Memory project configuration
+    """
+    try:
+        asyncio.run(initialize_database(app_config))
+    except Exception as e:
+        logger.error(f"Error during initialization: {e}")
+        # Continue execution even if initialization fails
+        # The command might still work, or will fail with a
+        # more specific error message

basic_memory/services/link_resolver.py

@@ -46,10 +46,17 @@ class LinkResolver:
             logger.debug(f"Found title match: {entity.title}")
             return entity
 
+        # 3. Try file path
+        found_path = await self.entity_repository.get_by_file_path(clean_text)
+        if found_path:
+            logger.debug(f"Found entity with path: {found_path.file_path}")
+            return found_path
+
+        # search if indicated
         if use_search and "*" not in clean_text:
             # 3. Fall back to search for fuzzy matching on title
             results = await self.search_service.search(
-                query=SearchQuery(title=clean_text, types=[SearchItemType.ENTITY]),
+                query=SearchQuery(title=clean_text, entity_types=[SearchItemType.ENTITY]),
             )
 
             if results:

basic_memory/services/search_service.py

@@ -181,17 +181,6 @@ class SearchService:
         Each type gets its own row in the search index with appropriate metadata.
         """
 
-        if entity.permalink is None:  # pragma: no cover
-            logger.error(
-                "Missing permalink for markdown entity",
-                entity_id=entity.id,
-                title=entity.title,
-                file_path=entity.file_path,
-            )
-            raise ValueError(
-                f"Entity permalink should not be None for markdown entity: {entity.id} ({entity.title})"
-            )
-
         content_stems = []
         content_snippet = ""
         title_variants = self._generate_variants(entity.title)
@@ -202,22 +191,13 @@ class SearchService:
             content_stems.append(content)
             content_snippet = f"{content[:250]}"
 
-        content_stems.extend(self._generate_variants(entity.permalink))
+        if entity.permalink:
+            content_stems.extend(self._generate_variants(entity.permalink))
+
         content_stems.extend(self._generate_variants(entity.file_path))
 
         entity_content_stems = "\n".join(p for p in content_stems if p and p.strip())
 
-        if entity.permalink is None:  # pragma: no cover
-            logger.error(
-                "Missing permalink for markdown entity",
-                entity_id=entity.id,
-                title=entity.title,
-                file_path=entity.file_path,
-            )
-            raise ValueError(
-                f"Entity permalink should not be None for markdown entity: {entity.id} ({entity.title})"
-            )
-
         # Index entity
         await self.repository.index_item(
             SearchIndexRow(