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

basic_memory/mcp/tools/search.py

@@ -1,5 +1,6 @@
 """Search tools for Basic Memory MCP server."""
 
+from textwrap import dedent
 from typing import List, Optional
 
 from loguru import logger
@@ -11,6 +12,162 @@ from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.search import SearchItemType, SearchQuery, SearchResponse
 
 
+def _format_search_error_response(error_message: str, query: str, search_type: str = "text") -> str:
+    """Format helpful error responses for search failures that guide users to successful searches."""
+
+    # FTS5 syntax errors
+    if "syntax error" in error_message.lower() or "fts5" in error_message.lower():
+        clean_query = (
+            query.replace('"', "")
+            .replace("(", "")
+            .replace(")", "")
+            .replace("+", "")
+            .replace("*", "")
+        )
+        return dedent(f"""
+            # Search Failed - Invalid Syntax
+
+            The search query '{query}' contains invalid syntax that the search engine cannot process.
+
+            ## Common syntax issues:
+            1. **Special characters**: Characters like `+`, `*`, `"`, `(`, `)` have special meaning in search
+            2. **Unmatched quotes**: Make sure quotes are properly paired
+            3. **Invalid operators**: Check AND, OR, NOT operators are used correctly
+
+            ## How to fix:
+            1. **Simplify your search**: Try using simple words instead: `{clean_query}`
+            2. **Remove special characters**: Use alphanumeric characters and spaces
+            3. **Use basic boolean operators**: `word1 AND word2`, `word1 OR word2`, `word1 NOT word2`
+
+            ## Examples of valid searches:
+            - Simple text: `project planning`
+            - Boolean AND: `project AND planning`
+            - Boolean OR: `meeting OR discussion`
+            - Boolean NOT: `project NOT archived`
+            - Grouped: `(project OR planning) AND notes`
+
+            ## Try again with:
+            ```
+            search_notes("INSERT_CLEAN_QUERY_HERE")
+            ```
+
+            Replace INSERT_CLEAN_QUERY_HERE with your simplified search terms.
+            """).strip()
+
+    # Project not found errors (check before general "not found")
+    if "project not found" in error_message.lower():
+        return dedent(f"""
+            # Search Failed - Project Not Found
+
+            The current project is not accessible or doesn't exist: {error_message}
+
+            ## How to resolve:
+            1. **Check available projects**: `list_projects()`
+            2. **Switch to valid project**: `switch_project("valid-project-name")`
+            3. **Verify project setup**: Ensure your project is properly configured
+
+            ## Current session info:
+            - Check current project: `get_current_project()`
+            - See available projects: `list_projects()`
+            """).strip()
+
+    # No results found
+    if "no results" in error_message.lower() or "not found" in error_message.lower():
+        simplified_query = (
+            " ".join(query.split()[:2])
+            if len(query.split()) > 2
+            else query.split()[0]
+            if query.split()
+            else "notes"
+        )
+        return dedent(f"""
+            # Search Complete - No Results Found
+
+            No content found matching '{query}' in the current project.
+
+            ## Suggestions to try:
+            1. **Broaden your search**: Try fewer or more general terms
+               - Instead of: `{query}`
+               - Try: `{simplified_query}`
+
+            2. **Check spelling**: Verify terms are spelled correctly
+            3. **Try different search types**:
+               - Text search: `search_notes("{query}", search_type="text")`
+               - Title search: `search_notes("{query}", search_type="title")`
+               - Permalink search: `search_notes("{query}", search_type="permalink")`
+
+            4. **Use boolean operators**:
+               - Try OR search for broader results
+
+            ## Check what content exists:
+            - Recent activity: `recent_activity(timeframe="7d")`
+            - List files: `list_directory("/")`
+            - Browse by folder: `list_directory("/notes")` or `list_directory("/docs")`
+            """).strip()
+
+    # Server/API errors
+    if "server error" in error_message.lower() or "internal" in error_message.lower():
+        return dedent(f"""
+            # Search Failed - Server Error
+
+            The search service encountered an error while processing '{query}': {error_message}
+
+            ## Immediate steps:
+            1. **Try again**: The error might be temporary
+            2. **Simplify the query**: Use simpler search terms
+            3. **Check project status**: Ensure your project is properly synced
+
+            ## Alternative approaches:
+            - Browse files directly: `list_directory("/")`
+            - Check recent activity: `recent_activity(timeframe="7d")`
+            - Try a different search type: `search_notes("{query}", search_type="title")`
+
+            ## If the problem persists:
+            The search index might need to be rebuilt. Send a message to support@basicmachines.co or check the project sync status.
+            """).strip()
+
+    # Permission/access errors
+    if (
+        "permission" in error_message.lower()
+        or "access" in error_message.lower()
+        or "forbidden" in error_message.lower()
+    ):
+        return f"""# Search Failed - Access Error
+
+You don't have permission to search in the current project: {error_message}
+
+## How to resolve:
+1. **Check your project access**: Verify you have read permissions for this project
+2. **Switch projects**: Try searching in a different project you have access to
+3. **Check authentication**: You might need to re-authenticate
+
+## Alternative actions:
+- List available projects: `list_projects()`
+- Switch to accessible project: `switch_project("project-name")`
+- Check current project: `get_current_project()`"""
+
+    # Generic fallback
+    return f"""# Search Failed
+
+Error searching for '{query}': {error_message}
+
+## General troubleshooting:
+1. **Check your query**: Ensure it uses valid search syntax
+2. **Try simpler terms**: Use basic words without special characters
+3. **Verify project access**: Make sure you can access the current project
+4. **Check recent activity**: `recent_activity(timeframe="7d")` to see if content exists
+
+## Alternative approaches:
+- Browse files: `list_directory("/")`
+- Try different search type: `search_notes("{query}", search_type="title")`
+- Search with filters: `search_notes("{query}", types=["entity"])`
+
+## Need help?
+- View recent changes: `recent_activity()`
+- List projects: `list_projects()` 
+- Check current project: `get_current_project()`"""
+
+
 @mcp.tool(
     description="Search across all content in the knowledge base.",
 )
@@ -23,7 +180,7 @@ async def search_notes(
     entity_types: Optional[List[str]] = None,
     after_date: Optional[str] = None,
     project: Optional[str] = None,
-) -> SearchResponse:
+) -> SearchResponse | str:
     """Search across all content in the knowledge base.
 
     This tool searches the knowledge base using full-text search, pattern matching,
@@ -113,10 +270,25 @@ async def search_notes(
     project_url = active_project.project_url
 
     logger.info(f"Searching for {search_query}")
-    response = await call_post(
-        client,
-        f"{project_url}/search/",
-        json=search_query.model_dump(),
-        params={"page": page, "page_size": page_size},
-    )
-    return SearchResponse.model_validate(response.json())
+
+    try:
+        response = await call_post(
+            client,
+            f"{project_url}/search/",
+            json=search_query.model_dump(),
+            params={"page": page, "page_size": page_size},
+        )
+        result = SearchResponse.model_validate(response.json())
+
+        # Check if we got no results and provide helpful guidance
+        if not result.results:
+            logger.info(f"Search returned no results for query: {query}")
+            # Don't treat this as an error, but the user might want guidance
+            # We return the empty result as normal - the user can decide if they need help
+
+        return result
+
+    except Exception as e:
+        logger.error(f"Search failed for query '{query}': {e}")
+        # Return formatted error message as string for better user experience
+        return _format_search_error_response(str(e), query, search_type)

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.fn(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)}")