basic-memory 0.13.0b4__py3-none-any.whl → 0.13.0b5__py3-none-any.whl

basic_memory/mcp/tools/sync_status.py

@@ -0,0 +1,254 @@
+"""Sync status tool for Basic Memory MCP server."""
+
+from typing import Optional
+
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.project_session import get_active_project
+
+
+def _get_all_projects_status() -> list[str]:
+    """Get status lines for all configured projects."""
+    status_lines = []
+
+    try:
+        from basic_memory.config import app_config
+        from basic_memory.services.sync_status_service import sync_status_tracker
+
+        if app_config.projects:
+            status_lines.extend(["", "---", "", "**All Projects Status:**"])
+
+            for project_name, project_path in app_config.projects.items():
+                # Check if this project has sync status
+                project_sync_status = sync_status_tracker.get_project_status(project_name)
+
+                if project_sync_status:
+                    # Project has tracked sync activity
+                    if project_sync_status.status.value == "watching":
+                        # Project is actively watching for changes (steady state)
+                        status_icon = "👁️"
+                        status_text = "Watching for changes"
+                    elif project_sync_status.status.value == "completed":
+                        # Sync completed but not yet watching - transitional state
+                        status_icon = "✅"
+                        status_text = "Sync completed"
+                    elif project_sync_status.status.value in ["scanning", "syncing"]:
+                        status_icon = "🔄"
+                        status_text = "Sync in progress"
+                        if project_sync_status.files_total > 0:
+                            progress_pct = (
+                                project_sync_status.files_processed
+                                / project_sync_status.files_total
+                            ) * 100
+                            status_text += f" ({project_sync_status.files_processed}/{project_sync_status.files_total}, {progress_pct:.0f}%)"
+                    elif project_sync_status.status.value == "failed":
+                        status_icon = "❌"
+                        status_text = f"Sync error: {project_sync_status.error or 'Unknown error'}"
+                    else:
+                        status_icon = "⏸️"
+                        status_text = project_sync_status.status.value.title()
+                else:
+                    # Project has no tracked sync activity - will be synced automatically
+                    status_icon = "⏳"
+                    status_text = "Pending sync"
+
+                status_lines.append(f"- {status_icon} **{project_name}**: {status_text}")
+
+    except Exception as e:
+        logger.debug(f"Could not get project config for comprehensive status: {e}")
+
+    return status_lines
+
+
+@mcp.tool(
+    description="""Check the status of file synchronization and background operations.
+    
+    Use this tool to:
+    - Check if file sync is in progress or completed
+    - Get detailed sync progress information  
+    - Understand if your files are fully indexed
+    - Get specific error details if sync operations failed
+    - Monitor initial project setup and legacy migration
+    
+    This covers all sync operations including:
+    - Initial project setup and file indexing
+    - Legacy project migration to unified database
+    - Ongoing file monitoring and updates
+    - Background processing of knowledge graphs
+    """,
+)
+async def sync_status(project: Optional[str] = None) -> str:
+    """Get current sync status and system readiness information.
+
+    This tool provides detailed information about any ongoing or completed
+    sync operations, helping users understand when their files are ready.
+
+    Args:
+        project: Optional project name to get project-specific context
+
+    Returns:
+        Formatted sync status with progress, readiness, and guidance
+    """
+    logger.info("MCP tool call tool=sync_status")
+
+    status_lines = []
+
+    try:
+        from basic_memory.services.sync_status_service import sync_status_tracker
+
+        # Get overall summary
+        summary = sync_status_tracker.get_summary()
+        is_ready = sync_status_tracker.is_ready
+
+        # Header
+        status_lines.extend(
+            [
+                "# Basic Memory Sync Status",
+                "",
+                f"**Current Status**: {summary}",
+                f"**System Ready**: {'✅ Yes' if is_ready else '🔄 Processing'}",
+                "",
+            ]
+        )
+
+        if is_ready:
+            status_lines.extend(
+                [
+                    "✅ **All sync operations completed**",
+                    "",
+                    "- File indexing is complete",
+                    "- Knowledge graphs are up to date",
+                    "- All Basic Memory tools are fully operational",
+                    "",
+                    "Your knowledge base is ready for use!",
+                ]
+            )
+
+            # Show all projects status even when ready
+            status_lines.extend(_get_all_projects_status())
+        else:
+            # System is still processing - show both active and all projects
+            all_sync_projects = sync_status_tracker.get_all_projects()
+
+            active_projects = [
+                p for p in all_sync_projects.values() if p.status.value in ["scanning", "syncing"]
+            ]
+            failed_projects = [p for p in all_sync_projects.values() if p.status.value == "failed"]
+
+            if active_projects:
+                status_lines.extend(
+                    [
+                        "🔄 **File synchronization in progress**",
+                        "",
+                        "Basic Memory is automatically processing all configured projects and building knowledge graphs.",
+                        "This typically takes 1-3 minutes depending on the amount of content.",
+                        "",
+                        "**Currently Processing:**",
+                    ]
+                )
+
+                for project_status in active_projects:
+                    progress = ""
+                    if project_status.files_total > 0:
+                        progress_pct = (
+                            project_status.files_processed / project_status.files_total
+                        ) * 100
+                        progress = f" ({project_status.files_processed}/{project_status.files_total}, {progress_pct:.0f}%)"
+
+                    status_lines.append(
+                        f"- **{project_status.project_name}**: {project_status.message}{progress}"
+                    )
+
+                status_lines.extend(
+                    [
+                        "",
+                        "**What's happening:**",
+                        "- Scanning and indexing markdown files",
+                        "- Building entity and relationship graphs",
+                        "- Setting up full-text search indexes",
+                        "- Processing file changes and updates",
+                        "",
+                        "**What you can do:**",
+                        "- Wait for automatic processing to complete - no action needed",
+                        "- Use this tool again to check progress",
+                        "- Simple operations may work already",
+                        "- All projects will be available once sync finishes",
+                    ]
+                )
+
+            # Handle failed projects (independent of active projects)
+            if failed_projects:
+                status_lines.extend(["", "❌ **Some projects failed to sync:**", ""])
+
+                for project_status in failed_projects:
+                    status_lines.append(
+                        f"- **{project_status.project_name}**: {project_status.error or 'Unknown error'}"
+                    )
+
+                status_lines.extend(
+                    [
+                        "",
+                        "**Next steps:**",
+                        "1. Check the logs for detailed error information",
+                        "2. Ensure file permissions allow read/write access",
+                        "3. Try restarting the MCP server",
+                        "4. If issues persist, consider filing a support issue",
+                    ]
+                )
+            elif not active_projects:
+                # No active or failed projects - must be pending
+                status_lines.extend(
+                    [
+                        "⏳ **Sync operations pending**",
+                        "",
+                        "File synchronization has been queued but hasn't started yet.",
+                        "This usually resolves automatically within a few seconds.",
+                    ]
+                )
+
+        # Add comprehensive project status for all configured projects
+        all_projects_status = _get_all_projects_status()
+        if all_projects_status:
+            status_lines.extend(all_projects_status)
+
+            # Add explanation about automatic syncing if there are unsynced projects
+            unsynced_count = sum(1 for line in all_projects_status if "⏳" in line)
+            if unsynced_count > 0 and not is_ready:
+                status_lines.extend(
+                    [
+                        "",
+                        "**Note**: All configured projects will be automatically synced during startup.",
+                        "You don't need to manually switch projects - Basic Memory handles this for you.",
+                    ]
+                )
+
+        # Add project context if provided
+        if project:
+            try:
+                active_project = get_active_project(project)
+                status_lines.extend(
+                    [
+                        "",
+                        "---",
+                        "",
+                        f"**Active Project**: {active_project.name}",
+                        f"**Project Path**: {active_project.home}",
+                    ]
+                )
+            except Exception as e:
+                logger.debug(f"Could not get project info: {e}")
+
+        return "\n".join(status_lines)
+
+    except Exception as e:
+        return f"""# Sync Status - Error
+
+❌ **Unable to check sync status**: {str(e)}
+
+**Troubleshooting:**
+- The system may still be starting up
+- Try waiting a few seconds and checking again  
+- Check logs for detailed error information
+- Consider restarting if the issue persists
+"""

basic_memory/mcp/tools/utils.py

@@ -506,3 +506,50 @@ async def call_delete(
 
     except HTTPStatusError as e:
         raise ToolError(error_message) from e
+
+
+def check_migration_status() -> Optional[str]:
+    """Check if sync/migration is in progress and return status message if so.
+
+    Returns:
+        Status message if sync is in progress, None if system is ready
+    """
+    try:
+        from basic_memory.services.sync_status_service import sync_status_tracker
+
+        if not sync_status_tracker.is_ready:
+            return sync_status_tracker.get_summary()
+        return None
+    except Exception:
+        # If there's any error checking sync status, assume ready
+        return None
+
+
+async def wait_for_migration_or_return_status(timeout: float = 5.0) -> Optional[str]:
+    """Wait briefly for sync/migration to complete, or return status message.
+
+    Args:
+        timeout: Maximum time to wait for sync completion
+
+    Returns:
+        Status message if sync is still in progress, None if ready
+    """
+    try:
+        from basic_memory.services.sync_status_service import sync_status_tracker
+        import asyncio
+
+        if sync_status_tracker.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:
+                return None
+            await asyncio.sleep(0.1)  # Check every 100ms
+
+        # Still not ready after timeout
+        return sync_status_tracker.get_summary()
+    except Exception:  # pragma: no cover
+        # If there's any error, assume ready
+        return None

basic_memory/mcp/tools/view_note.py

@@ -0,0 +1,66 @@
+"""View note tool for Basic Memory MCP server."""
+
+from textwrap import dedent
+from typing import Optional
+
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.read_note import read_note
+
+
+@mcp.tool(
+    description="View a note as a formatted artifact for better readability.",
+)
+async def view_note(
+    identifier: str, page: int = 1, page_size: int = 10, project: Optional[str] = None
+) -> str:
+    """View a markdown note as a formatted artifact.
+
+    This tool reads a note using the same logic as read_note but displays the content
+    as a markdown artifact for better viewing experience in Claude Desktop.
+
+    After calling this tool, create an artifact using the returned content to display
+    the note in a readable format. The tool returns the note content that should be
+    used to create a markdown artifact.
+
+    Args:
+        identifier: The title or permalink of the note to view
+        page: Page number for paginated results (default: 1)
+        page_size: Number of items per page (default: 10)
+        project: Optional project name to read from. If not provided, uses current active project.
+
+    Returns:
+        The note content as a markdown artifact with a confirmation message.
+    """
+
+    logger.info(f"Viewing note: {identifier}")
+
+    # Call the existing read_note logic
+    content = await read_note(identifier, page, page_size, project)
+
+    # Check if this is an error message (note not found)
+    if "# Note Not Found:" in content:
+        return content  # Return error message directly instead of creating artifact
+
+    # Extract title from content if possible
+    title = identifier
+    lines = content.split("\n")
+    for line in lines:
+        if line.startswith("title:"):
+            # Extract title from frontmatter
+            title = line.split("title:", 1)[1].strip().strip('"').strip("'")
+            break
+        elif line.startswith("# "):
+            # Extract title from first heading
+            title = line[2:].strip()
+            break
+
+    # Return the artifact XML as part of the response
+    artifact = f'<artifact identifier="note-{hash(identifier) & 0x7FFFFFFF}" type="text/markdown" title="{title}">\n{content}\n</artifact>'
+
+    return dedent(f"""
+            <instructions>
+            Create an artifact using the returned artifact content to display the note in a readable format.
+            </instructions>
+            {artifact}\n\n✅ Note displayed as artifact: **{title}**""")

basic_memory/mcp/tools/write_note.py

@@ -54,7 +54,8 @@ async def write_note(
     Args:
         title: The title of the note
         content: Markdown content for the note, can include observations and relations
-        folder: the folder where the file should be saved
+        folder: Folder path relative to project root where the file should be saved.
+                Use forward slashes (/) as separators. Examples: "notes", "projects/2025", "research/ml"
         tags: Tags to categorize the note. Can be a list of strings, a comma-separated string, or None.
               Note: If passing from external MCP clients, use a string format (e.g. "tag1,tag2,tag3")
         project: Optional project name to write to. If not provided, uses current active project.
@@ -69,6 +70,13 @@ async def write_note(
     """
     logger.info(f"MCP tool call tool=write_note folder={folder}, title={title}, tags={tags}")
 
+    # 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)
+    if migration_status:  # pragma: no cover
+        return f"# System Status\n\n{migration_status}\n\nPlease wait for migration to complete before creating notes."
+
     # Process tags using the helper function
     tag_list = parse_tags(tags)
     # Create the entity request
@@ -120,7 +128,10 @@ async def write_note(
         summary.append(f"- Resolved: {resolved}")
         if unresolved:
             summary.append(f"- Unresolved: {unresolved}")
-            summary.append("\nUnresolved relations will be retried on next sync.")
+            summary.append("\nNote: Unresolved relations point to entities that don't exist yet.")
+            summary.append(
+                "They will be automatically resolved when target entities are created or during sync operations."
+            )
 
     if tag_list:
         summary.append(f"\n## Tags\n- {', '.join(tag_list)}")

basic_memory/repository/search_repository.py

@@ -128,34 +128,90 @@ class SearchRepository:
             is_prefix: Whether to add prefix search capability (* suffix)
 
         For FTS5:
-        - Special characters and phrases need to be quoted
-        - Terms with spaces or special chars need quotes
         - 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
         """
-        if "*" in term:
-            return 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):
             return term
 
-        # List of FTS5 special characters that need escaping/quoting
-        special_chars = ["/", "-", ".", " ", "(", ")", "[", "]", '"', "'"]
+        # 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):
+            return term
 
-        # Check if term contains any special characters
-        needs_quotes = any(c in term for c in special_chars)
+        # Characters that can cause FTS5 syntax errors when used as operators
+        # We're more conservative here - only quote when we detect problematic patterns
+        problematic_chars = [
+            '"',
+            "'",
+            "(",
+            ")",
+            "[",
+            "]",
+            "{",
+            "}",
+            "+",
+            "!",
+            "@",
+            "#",
+            "$",
+            "%",
+            "^",
+            "&",
+            "=",
+            "|",
+            "\\",
+            "~",
+            "`",
+        ]
 
-        if needs_quotes:
-            # Escape any existing quotes by doubling them
-            escaped_term = term.replace('"', '""')
-            # Quote the entire term to handle special characters safely
-            if is_prefix and not ("/" in term and term.endswith(".md")):
-                # For search terms (not file paths), add prefix matching
-                term = f'"{escaped_term}"*'
+        # Characters that indicate we should quote (spaces, dots, colons, etc.)
+        # Adding hyphens here because FTS5 can have issues with hyphens followed by wildcards
+        needs_quoting_chars = [" ", ".", ":", ";", ",", "<", ">", "?", "/", "-"]
+
+        # Check if term needs quoting
+        has_problematic = any(c in term for c in problematic_chars)
+        has_spaces_or_special = any(c in term for c in needs_quoting_chars)
+
+        if has_problematic or has_spaces_or_special:
+            # Handle multi-word queries differently from special character queries
+            if " " in term and not any(c in term for c in problematic_chars):
+                # Check if any individual word contains special characters that need quoting
+                words = term.strip().split()
+                has_special_in_words = any(
+                    any(c in word for c in needs_quoting_chars if c != " ") for word in words
+                )
+
+                if not has_special_in_words:
+                    # For multi-word queries with simple words (like "emoji unicode"),
+                    # use boolean AND to handle word order variations
+                    if is_prefix:
+                        # Add prefix wildcard to each word for better matching
+                        prepared_words = [f"{word}*" for word in words if word]
+                    else:
+                        prepared_words = words
+                    term = " AND ".join(prepared_words)
+                else:
+                    # If any word has special characters, quote the entire phrase
+                    escaped_term = term.replace('"', '""')
+                    if is_prefix and not ("/" in term and term.endswith(".md")):
+                        term = f'"{escaped_term}"*'
+                    else:
+                        term = f'"{escaped_term}"'
             else:
-                # For file paths, use exact matching
-                term = f'"{escaped_term}"'
+                # For terms with problematic characters or file paths, use exact phrase matching
+                # Escape any existing quotes by doubling them
+                escaped_term = term.replace('"', '""')
+                # Quote the entire term to handle special characters safely
+                if is_prefix and not ("/" in term and term.endswith(".md")):
+                    # For search terms (not file paths), add prefix matching
+                    term = f'"{escaped_term}"*'
+                else:
+                    # For file paths, use exact matching
+                    term = f'"{escaped_term}"'
         elif is_prefix:
             # Only add wildcard for simple terms without special characters
             term = f"{term}*"
@@ -208,15 +264,21 @@ class SearchRepository:
 
         # Handle permalink match search, supports *
         if permalink_match:
-            # Clean and prepare permalink for FTS5 GLOB match
-            permalink_text = self._prepare_search_term(
-                permalink_match.lower().strip(), is_prefix=False
-            )
+            # For GLOB patterns, don't use _prepare_search_term as it will quote slashes
+            # GLOB patterns need to preserve their syntax
+            permalink_text = permalink_match.lower().strip()
             params["permalink"] = permalink_text
             if "*" in permalink_match:
                 conditions.append("permalink GLOB :permalink")
             else:
-                conditions.append("permalink MATCH :permalink")
+                # For exact matches without *, we can use FTS5 MATCH
+                # but only prepare the term if it doesn't look like a path
+                if "/" in permalink_text:
+                    conditions.append("permalink = :permalink")
+                else:
+                    permalink_text = self._prepare_search_term(permalink_text, is_prefix=False)
+                    params["permalink"] = permalink_text
+                    conditions.append("permalink MATCH :permalink")
 
         # Handle entity type filter
         if search_item_types:
@@ -273,9 +335,20 @@ class SearchRepository:
         """
 
         logger.trace(f"Search {sql} params: {params}")
-        async with db.scoped_session(self.session_maker) as session:
-            result = await session.execute(text(sql), params)
-            rows = result.fetchall()
+        try:
+            async with db.scoped_session(self.session_maker) as session:
+                result = await session.execute(text(sql), params)
+                rows = result.fetchall()
+        except Exception as e:
+            # Handle FTS5 syntax errors and provide user-friendly feedback
+            if "fts5: syntax error" in str(e).lower():  # pragma: no cover
+                logger.warning(f"FTS5 syntax error for search term: {search_text}, error: {e}")
+                # Return empty results rather than crashing
+                return []
+            else:
+                # Re-raise other database errors
+                logger.error(f"Database error during search: {e}")
+                raise
 
         results = [
             SearchIndexRow(

basic_memory/schemas/base.py

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