basic-memory 0.13.7.dev1__py3-none-any.whl → 0.14.0__py3-none-any.whl

basic_memory/mcp/tools/utils.py

@@ -525,11 +525,16 @@ def check_migration_status() -> Optional[str]:
         return None
 
 
-async def wait_for_migration_or_return_status(timeout: float = 5.0) -> Optional[str]:
+async def wait_for_migration_or_return_status(
+    timeout: float = 5.0, project_name: Optional[str] = None
+) -> Optional[str]:
     """Wait briefly for sync/migration to complete, or return status message.
 
     Args:
         timeout: Maximum time to wait for sync completion
+        project_name: Optional project name to check specific project status.
+                     If provided, only checks that project's readiness.
+                     If None, uses global status check (legacy behavior).
 
     Returns:
         Status message if sync is still in progress, None if ready
@@ -538,18 +543,36 @@ async def wait_for_migration_or_return_status(timeout: float = 5.0) -> Optional[
         from basic_memory.services.sync_status_service import sync_status_tracker
         import asyncio
 
-        if sync_status_tracker.is_ready:
+        # Check if we should use project-specific or global status
+        def is_ready() -> bool:
+            if project_name:
+                return sync_status_tracker.is_project_ready(project_name)
+            return sync_status_tracker.is_ready
+
+        if is_ready():
             return None
 
         # Wait briefly for sync to complete
         start_time = asyncio.get_event_loop().time()
         while (asyncio.get_event_loop().time() - start_time) < timeout:
-            if sync_status_tracker.is_ready:
+            if is_ready():
                 return None
             await asyncio.sleep(0.1)  # Check every 100ms
 
         # Still not ready after timeout
-        return sync_status_tracker.get_summary()
+        if project_name:
+            # For project-specific checks, get project status details
+            project_status = sync_status_tracker.get_project_status(project_name)
+            if project_status and project_status.status.value == "failed":
+                error_msg = project_status.error or "Unknown sync error"
+                return f"❌ Sync failed for project '{project_name}': {error_msg}"
+            elif project_status:
+                return f"🔄 Project '{project_name}' is still syncing: {project_status.message}"
+            else:
+                return f"⚠️ Project '{project_name}' status unknown"
+        else:
+            # Fall back to global summary for legacy calls
+            return sync_status_tracker.get_summary()
     except Exception:  # pragma: no cover
         # If there's any error, assume ready
         return None

basic_memory/mcp/tools/write_note.py

@@ -72,10 +72,15 @@ async def write_note(
     """
     logger.info(f"MCP tool call tool=write_note folder={folder}, title={title}, tags={tags}")
 
+    # Get the active project first to check project-specific sync status
+    active_project = get_active_project(project)
+
     # Check migration status and wait briefly if needed
     from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
 
-    migration_status = await wait_for_migration_or_return_status(timeout=5.0)
+    migration_status = await wait_for_migration_or_return_status(
+        timeout=5.0, project_name=active_project.name
+    )
     if migration_status:  # pragma: no cover
         return f"# System Status\n\n{migration_status}\n\nPlease wait for migration to complete before creating notes."
 
@@ -91,7 +96,6 @@ async def write_note(
         content=content,
         entity_metadata=metadata,
     )
-    active_project = get_active_project(project)
     project_url = active_project.project_url
 
     # Create or update via knowledge API

basic_memory/repository/entity_repository.py

@@ -102,14 +102,14 @@ class EntityRepository(Repository[Entity]):
 
     async def upsert_entity(self, entity: Entity) -> Entity:
         """Insert or update entity using a hybrid approach.
-        
+
         This method provides a cleaner alternative to the try/catch approach
-        for handling permalink and file_path conflicts. It first tries direct 
+        for handling permalink and file_path conflicts. It first tries direct
         insertion, then handles conflicts intelligently.
-        
+
         Args:
             entity: The entity to insert or update
-            
+
         Returns:
             The inserted or updated entity
         """
@@ -117,98 +117,102 @@ class EntityRepository(Repository[Entity]):
         async with db.scoped_session(self.session_maker) as session:
             # Set project_id if applicable and not already set
             self._set_project_id_if_needed(entity)
-            
+
             # Check for existing entity with same file_path first
             existing_by_path = await session.execute(
                 select(Entity).where(
-                    Entity.file_path == entity.file_path,
-                    Entity.project_id == entity.project_id
+                    Entity.file_path == entity.file_path, Entity.project_id == entity.project_id
                 )
             )
             existing_path_entity = existing_by_path.scalar_one_or_none()
-            
+
             if existing_path_entity:
                 # Update existing entity with same file path
                 for key, value in {
-                    'title': entity.title,
-                    'entity_type': entity.entity_type,
-                    'entity_metadata': entity.entity_metadata,
-                    'content_type': entity.content_type,
-                    'permalink': entity.permalink,
-                    'checksum': entity.checksum,
-                    'updated_at': entity.updated_at,
+                    "title": entity.title,
+                    "entity_type": entity.entity_type,
+                    "entity_metadata": entity.entity_metadata,
+                    "content_type": entity.content_type,
+                    "permalink": entity.permalink,
+                    "checksum": entity.checksum,
+                    "updated_at": entity.updated_at,
                 }.items():
                     setattr(existing_path_entity, key, value)
-                
+
                 await session.flush()
                 # Return with relationships loaded
                 query = (
-                    select(Entity)
+                    self.select()
                     .where(Entity.file_path == entity.file_path)
                     .options(*self.get_load_options())
                 )
                 result = await session.execute(query)
                 found = result.scalar_one_or_none()
                 if not found:  # pragma: no cover
-                    raise RuntimeError(f"Failed to retrieve entity after update: {entity.file_path}")
+                    raise RuntimeError(
+                        f"Failed to retrieve entity after update: {entity.file_path}"
+                    )
                 return found
-            
+
             # No existing entity with same file_path, try insert
             try:
                 # Simple insert for new entity
                 session.add(entity)
                 await session.flush()
-                
+
                 # Return with relationships loaded
                 query = (
-                    select(Entity)
+                    self.select()
                     .where(Entity.file_path == entity.file_path)
                     .options(*self.get_load_options())
                 )
                 result = await session.execute(query)
                 found = result.scalar_one_or_none()
                 if not found:  # pragma: no cover
-                    raise RuntimeError(f"Failed to retrieve entity after insert: {entity.file_path}")
+                    raise RuntimeError(
+                        f"Failed to retrieve entity after insert: {entity.file_path}"
+                    )
                 return found
-                
+
             except IntegrityError:
                 # Could be either file_path or permalink conflict
                 await session.rollback()
-                
+
                 # Check if it's a file_path conflict (race condition)
                 existing_by_path_check = await session.execute(
                     select(Entity).where(
-                        Entity.file_path == entity.file_path,
-                        Entity.project_id == entity.project_id
+                        Entity.file_path == entity.file_path, Entity.project_id == entity.project_id
                     )
                 )
                 race_condition_entity = existing_by_path_check.scalar_one_or_none()
-                
+
                 if race_condition_entity:
                     # Race condition: file_path conflict detected after our initial check
                     # Update the existing entity instead
                     for key, value in {
-                        'title': entity.title,
-                        'entity_type': entity.entity_type,
-                        'entity_metadata': entity.entity_metadata,
-                        'content_type': entity.content_type,
-                        'permalink': entity.permalink,
-                        'checksum': entity.checksum,
-                        'updated_at': entity.updated_at,
+                        "title": entity.title,
+                        "entity_type": entity.entity_type,
+                        "entity_metadata": entity.entity_metadata,
+                        "content_type": entity.content_type,
+                        "permalink": entity.permalink,
+                        "checksum": entity.checksum,
+                        "updated_at": entity.updated_at,
                     }.items():
                         setattr(race_condition_entity, key, value)
-                    
+
                     await session.flush()
                     # Return the updated entity with relationships loaded
                     query = (
-                        select(Entity)
+                        self.select()
                         .where(Entity.file_path == entity.file_path)
                         .options(*self.get_load_options())
                     )
                     result = await session.execute(query)
                     found = result.scalar_one_or_none()
                     if not found:  # pragma: no cover
-                        raise RuntimeError(f"Failed to retrieve entity after race condition update: {entity.file_path}")
+                        raise RuntimeError(
+                            f"Failed to retrieve entity after race condition update: {entity.file_path}"
+                        )
                     return found
                 else:
                     # Must be permalink conflict - generate unique permalink
@@ -218,14 +222,13 @@ class EntityRepository(Repository[Entity]):
         """Handle permalink conflicts by generating a unique permalink."""
         base_permalink = entity.permalink
         suffix = 1
-        
+
         # Find a unique permalink
         while True:
             test_permalink = f"{base_permalink}-{suffix}"
             existing = await session.execute(
                 select(Entity).where(
-                    Entity.permalink == test_permalink,
-                    Entity.project_id == entity.project_id
+                    Entity.permalink == test_permalink, Entity.project_id == entity.project_id
                 )
             )
             if existing.scalar_one_or_none() is None:
@@ -233,14 +236,14 @@ class EntityRepository(Repository[Entity]):
                 entity.permalink = test_permalink
                 break
             suffix += 1
-            
+
         # Insert with unique permalink (no conflict possible now)
         session.add(entity)
         await session.flush()
-        
+
         # Return the inserted entity with relationships loaded
         query = (
-            select(Entity)
+            self.select()
             .where(Entity.file_path == entity.file_path)
             .options(*self.get_load_options())
         )

basic_memory/repository/search_repository.py

@@ -1,6 +1,7 @@
 """Repository for search operations."""
 
 import json
+import re
 import time
 from dataclasses import dataclass
 from datetime import datetime
@@ -120,23 +121,141 @@ class SearchRepository:
             logger.error(f"Error initializing search index: {e}")
             raise e
 
-    def _prepare_search_term(self, term: str, is_prefix: bool = True) -> str:
-        """Prepare a search term for FTS5 query.
+    def _prepare_boolean_query(self, query: str) -> str:
+        """Prepare a Boolean query by quoting individual terms while preserving operators.
 
         Args:
-            term: The search term to prepare
+            query: A Boolean query like "tier1-test AND unicode" or "(hello OR world) NOT test"
+
+        Returns:
+            A properly formatted Boolean query with quoted terms that need quoting
+        """
+        # Define Boolean operators and their boundaries
+        boolean_pattern = r"(\bAND\b|\bOR\b|\bNOT\b)"
+
+        # Split the query by Boolean operators, keeping the operators
+        parts = re.split(boolean_pattern, query)
+
+        processed_parts = []
+        for part in parts:
+            part = part.strip()
+            if not part:
+                continue
+
+            # If it's a Boolean operator, keep it as is
+            if part in ["AND", "OR", "NOT"]:
+                processed_parts.append(part)
+            else:
+                # Handle parentheses specially - they should be preserved for grouping
+                if "(" in part or ")" in part:
+                    # Parse parenthetical expressions carefully
+                    processed_part = self._prepare_parenthetical_term(part)
+                    processed_parts.append(processed_part)
+                else:
+                    # This is a search term - for Boolean queries, don't add prefix wildcards
+                    prepared_term = self._prepare_single_term(part, is_prefix=False)
+                    processed_parts.append(prepared_term)
+
+        return " ".join(processed_parts)
+
+    def _prepare_parenthetical_term(self, term: str) -> str:
+        """Prepare a term that contains parentheses, preserving the parentheses for grouping.
+
+        Args:
+            term: A term that may contain parentheses like "(hello" or "world)" or "(hello OR world)"
+
+        Returns:
+            A properly formatted term with parentheses preserved
+        """
+        # Handle terms that start/end with parentheses but may contain quotable content
+        result = ""
+        i = 0
+        while i < len(term):
+            if term[i] in "()":
+                # Preserve parentheses as-is
+                result += term[i]
+                i += 1
+            else:
+                # Find the next parenthesis or end of string
+                start = i
+                while i < len(term) and term[i] not in "()":
+                    i += 1
+
+                # Extract the content between parentheses
+                content = term[start:i].strip()
+                if content:
+                    # Only quote if it actually needs quoting (has hyphens, special chars, etc)
+                    # but don't quote if it's just simple words
+                    if self._needs_quoting(content):
+                        escaped_content = content.replace('"', '""')
+                        result += f'"{escaped_content}"'
+                    else:
+                        result += content
+
+        return result
+
+    def _needs_quoting(self, term: str) -> bool:
+        """Check if a term needs to be quoted for FTS5 safety.
+
+        Args:
+            term: The term to check
+
+        Returns:
+            True if the term should be quoted
+        """
+        if not term or not term.strip():
+            return False
+
+        # Characters that indicate we should quote (excluding parentheses which are valid syntax)
+        needs_quoting_chars = [
+            " ",
+            ".",
+            ":",
+            ";",
+            ",",
+            "<",
+            ">",
+            "?",
+            "/",
+            "-",
+            "'",
+            '"',
+            "[",
+            "]",
+            "{",
+            "}",
+            "+",
+            "!",
+            "@",
+            "#",
+            "$",
+            "%",
+            "^",
+            "&",
+            "=",
+            "|",
+            "\\",
+            "~",
+            "`",
+        ]
+
+        return any(c in term for c in needs_quoting_chars)
+
+    def _prepare_single_term(self, term: str, is_prefix: bool = True) -> str:
+        """Prepare a single search term (no Boolean operators).
+
+        Args:
+            term: A single search term
             is_prefix: Whether to add prefix search capability (* suffix)
 
-        For FTS5:
-        - Boolean operators (AND, OR, NOT) are preserved for complex queries
-        - Terms with FTS5 special characters are quoted to prevent syntax errors
-        - Simple terms get prefix wildcards for better matching
+        Returns:
+            A properly formatted single term
         """
-        # Check for explicit boolean operators - if present, return the term as is
-        boolean_operators = [" AND ", " OR ", " NOT "]
-        if any(op in f" {term} " for op in boolean_operators):
+        if not term or not term.strip():
             return term
 
+        term = term.strip()
+
         # Check if term is already a proper wildcard pattern (alphanumeric + *)
         # e.g., "hello*", "test*world" - these should be left alone
         if "*" in term and all(c.isalnum() or c in "*_-" for c in term):
@@ -218,6 +337,26 @@ class SearchRepository:
 
         return term
 
+    def _prepare_search_term(self, term: str, is_prefix: bool = True) -> str:
+        """Prepare a search term for FTS5 query.
+
+        Args:
+            term: The search term to prepare
+            is_prefix: Whether to add prefix search capability (* suffix)
+
+        For FTS5:
+        - Boolean operators (AND, OR, NOT) are preserved for complex queries
+        - Terms with FTS5 special characters are quoted to prevent syntax errors
+        - Simple terms get prefix wildcards for better matching
+        """
+        # Check for explicit boolean operators - if present, process as Boolean query
+        boolean_operators = [" AND ", " OR ", " NOT "]
+        if any(op in f" {term} " for op in boolean_operators):
+            return self._prepare_boolean_query(term)
+
+        # For non-Boolean queries, use the single term preparation logic
+        return self._prepare_single_term(term, is_prefix)
+
     async def search(
         self,
         search_text: Optional[str] = None,
@@ -242,19 +381,10 @@ class SearchRepository:
                 # For wildcard searches, don't add any text conditions - return all results
                 pass
             else:
-                # Check for explicit boolean operators - only detect them in proper boolean contexts
-                has_boolean = any(op in f" {search_text} " for op in [" AND ", " OR ", " NOT "])
-
-                if has_boolean:
-                    # If boolean operators are present, use the raw query
-                    # No need to prepare it, FTS5 will understand the operators
-                    params["text"] = search_text
-                    conditions.append("(title MATCH :text OR content_stems MATCH :text)")
-                else:
-                    # Standard search with term preparation
-                    processed_text = self._prepare_search_term(search_text.strip())
-                    params["text"] = processed_text
-                    conditions.append("(title MATCH :text OR content_stems MATCH :text)")
+                # Use _prepare_search_term to handle both Boolean and non-Boolean queries
+                processed_text = self._prepare_search_term(search_text.strip())
+                params["text"] = processed_text
+                conditions.append("(title MATCH :text OR content_stems MATCH :text)")
 
         # Handle title match search
         if title:

basic_memory/schemas/memory.py

@@ -134,7 +134,7 @@ class RelationSummary(BaseModel):
     file_path: str
     permalink: str
     relation_type: str
-    from_entity: str
+    from_entity: Optional[str] = None
     to_entity: Optional[str] = None
     created_at: datetime
 

basic_memory/schemas/response.py

@@ -131,7 +131,7 @@ class EntityResponse(SQLAlchemyModel):
     }
     """
 
-    permalink: Permalink
+    permalink: Optional[Permalink]
     title: str
     file_path: str
     entity_type: EntityType

basic_memory/services/entity_service.py

@@ -302,7 +302,7 @@ class EntityService(BaseService[EntityModel]):
 
         Creates the entity with null checksum to indicate sync not complete.
         Relations will be added in second pass.
-        
+
         Uses UPSERT approach to handle permalink/file_path conflicts cleanly.
         """
         logger.debug(f"Creating entity: {markdown.frontmatter.title} file_path: {file_path}")
@@ -310,7 +310,7 @@ class EntityService(BaseService[EntityModel]):
 
         # Mark as incomplete because we still need to add relations
         model.checksum = None
-        
+
         # Use UPSERT to handle conflicts cleanly
         try:
             return await self.repository.upsert_entity(model)
@@ -682,8 +682,8 @@ class EntityService(BaseService[EntityModel]):
             # 6. Prepare database updates
             updates = {"file_path": destination_path}
 
-            # 7. Update permalink if configured
-            if app_config.update_permalinks_on_move:
+            # 7. Update permalink if configured or if entity has null permalink
+            if 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)
 
@@ -693,7 +693,12 @@ class EntityService(BaseService[EntityModel]):
                 )
 
                 updates["permalink"] = new_permalink
-                logger.info(f"Updated permalink: {old_permalink} -> {new_permalink}")
+                if old_permalink is None:
+                    logger.info(
+                        f"Generated permalink for entity with null permalink: {new_permalink}"
+                    )
+                else:
+                    logger.info(f"Updated permalink: {old_permalink} -> {new_permalink}")
 
             # 8. Recalculate checksum
             new_checksum = await self.file_service.compute_checksum(destination_path)

basic_memory/services/initialization.py

@@ -21,9 +21,9 @@ async def initialize_database(app_config: BasicMemoryConfig) -> None:
 
     Args:
         app_config: The Basic Memory project configuration
-        
+
     Note:
-        Database migrations are now handled automatically when the database 
+        Database migrations are now handled automatically when the database
         connection is first established via get_or_create_db().
     """
     # Trigger database initialization and migrations by getting the database connection
@@ -50,7 +50,9 @@ async def reconcile_projects_with_config(app_config: BasicMemoryConfig):
 
     # Get database session - migrations handled centrally
     _, session_maker = await db.get_or_create_db(
-        db_path=app_config.database_path, db_type=db.DatabaseType.FILESYSTEM, ensure_migrations=False
+        db_path=app_config.database_path,
+        db_type=db.DatabaseType.FILESYSTEM,
+        ensure_migrations=False,
     )
     project_repository = ProjectRepository(session_maker)
 
@@ -71,7 +73,9 @@ async def reconcile_projects_with_config(app_config: BasicMemoryConfig):
 async def migrate_legacy_projects(app_config: BasicMemoryConfig):
     # Get database session - migrations handled centrally
     _, session_maker = await db.get_or_create_db(
-        db_path=app_config.database_path, db_type=db.DatabaseType.FILESYSTEM, ensure_migrations=False
+        db_path=app_config.database_path,
+        db_type=db.DatabaseType.FILESYSTEM,
+        ensure_migrations=False,
     )
     logger.info("Migrating legacy projects...")
     project_repository = ProjectRepository(session_maker)
@@ -140,7 +144,9 @@ async def initialize_file_sync(
 
     # Load app configuration - migrations handled centrally
     _, session_maker = await db.get_or_create_db(
-        db_path=app_config.database_path, db_type=db.DatabaseType.FILESYSTEM, ensure_migrations=False
+        db_path=app_config.database_path,
+        db_type=db.DatabaseType.FILESYSTEM,
+        ensure_migrations=False,
     )
     project_repository = ProjectRepository(session_maker)
 

basic_memory/services/project_service.py

@@ -154,6 +154,15 @@ class ProjectService:
 
         logger.info(f"Project '{name}' set as default in configuration and database")
 
+        # Refresh MCP session to pick up the new default project
+        try:
+            from basic_memory.mcp.project_session import session
+
+            session.refresh_from_config()
+        except ImportError:  # pragma: no cover
+            # MCP components might not be available in all contexts (e.g., CLI-only usage)
+            logger.debug("MCP session not available, skipping session refresh")
+
     async def _ensure_single_default_project(self) -> None:
         """Ensure only one project has is_default=True.
 
@@ -274,6 +283,15 @@ class ProjectService:
 
         logger.info("Project synchronization complete")
 
+        # Refresh MCP session to ensure it's in sync with current config
+        try:
+            from basic_memory.mcp.project_session import session
+
+            session.refresh_from_config()
+        except ImportError:
+            # MCP components might not be available in all contexts
+            logger.debug("MCP session not available, skipping session refresh")
+
     async def update_project(  # pragma: no cover
         self, name: str, updated_path: Optional[str] = None, is_active: Optional[bool] = None
     ) -> None:

basic_memory/services/sync_status_service.py

@@ -131,6 +131,23 @@ class SyncStatusTracker:
         """Check if system is ready (no sync in progress)."""
         return self._global_status in (SyncStatus.IDLE, SyncStatus.COMPLETED)
 
+    def is_project_ready(self, project_name: str) -> bool:
+        """Check if a specific project is ready for operations.
+
+        Args:
+            project_name: Name of the project to check
+
+        Returns:
+            True if the project is ready (completed, watching, or not tracked),
+            False if the project is syncing, scanning, or failed
+        """
+        project_status = self._project_statuses.get(project_name)
+        if not project_status:
+            # Project not tracked = ready (likely hasn't been synced yet)
+            return True
+
+        return project_status.status in (SyncStatus.COMPLETED, SyncStatus.WATCHING, SyncStatus.IDLE)
+
     def get_project_status(self, project_name: str) -> Optional[ProjectSyncStatus]:
         """Get status for a specific project."""
         return self._project_statuses.get(project_name)