basic-memory 0.15.0__py3-none-any.whl → 0.15.1__py3-none-any.whl

basic_memory/mcp/tools/sync_status.py

@@ -6,7 +6,7 @@ from loguru import logger
 from fastmcp import Context
 
 from basic_memory.config import ConfigManager
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.services.sync_status_service import sync_status_tracker
@@ -95,162 +95,167 @@ async def sync_status(project: Optional[str] = None, context: Context | None = N
     """
     logger.info("MCP tool call tool=sync_status")
 
-    status_lines = []
+    async with get_client() as client:
+        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:
+        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(
                 [
-                    "✅ **All sync operations completed**",
+                    "# Basic Memory Sync Status",
                     "",
-                    "- File indexing is complete",
-                    "- Knowledge graphs are up to date",
-                    "- All Basic Memory tools are fully operational",
+                    f"**Current Status**: {summary}",
+                    f"**System Ready**: {'✅ Yes' if is_ready else '🔄 Processing'}",
                     "",
-                    "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:
+            if is_ready:
                 status_lines.extend(
                     [
-                        "🔄 **File synchronization in progress**",
+                        "✅ **All sync operations completed**",
                         "",
-                        "Basic Memory is automatically processing all configured projects and building knowledge graphs.",
-                        "This typically takes 1-3 minutes depending on the amount of content.",
+                        "- File indexing is complete",
+                        "- Knowledge graphs are up to date",
+                        "- All Basic Memory tools are fully operational",
                         "",
-                        "**Currently Processing:**",
+                        "Your knowledge base is ready for use!",
                     ]
                 )
 
-                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}%)"
+                # 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()
 
-                    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:**", ""])
+                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"
+                ]
 
-                for project_status in failed_projects:
-                    status_lines.append(
-                        f"- **{project_status.project_name}**: {project_status.error or 'Unknown error'}"
+                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:**",
+                        ]
                     )
 
-                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.",
-                    ]
-                )
+                    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",
+                            "- Settings 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",
+                        ]
+                    )
 
-        # 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)
+                # 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 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.",
-                    ]
-                )
+            # 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.",
+                        ]
+                    )
 
-        # Add project context if provided
-        if project:
-            try:
-                active_project = await get_active_project(client, project, context)
-                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}")
+            # Add project context if provided
+            if project:
+                try:
+                    active_project = await get_active_project(client, project, context)
+                    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)
+            return "\n".join(status_lines)
 
-    except Exception as e:
-        return f"""# Sync Status - Error
+        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  
+- 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

@@ -23,8 +23,6 @@ from httpx._types import (
 from loguru import logger
 from mcp.server.fastmcp.exceptions import ToolError
 
-from basic_memory.mcp.tools.headers import inject_auth_header
-
 
 def get_error_message(
     status_code: int, url: URL | str, method: str, msg: Optional[str] = None
@@ -110,7 +108,6 @@ async def call_get(
     logger.debug(f"Calling GET '{url}' params: '{params}'")
     error_message = None
 
-    headers = inject_auth_header(headers)
     try:
         response = await client.get(
             url,
@@ -196,9 +193,6 @@ async def call_put(
     logger.debug(f"Calling PUT '{url}'")
     error_message = None
 
-    # Inject JWT from FastMCP context if available
-    headers = inject_auth_header(headers)
-
     try:
         response = await client.put(
             url,
@@ -288,9 +282,6 @@ async def call_patch(
     """
     logger.debug(f"Calling PATCH '{url}'")
 
-    # Inject JWT from FastMCP context if available
-    headers = inject_auth_header(headers)
-
     try:
         response = await client.patch(
             url,
@@ -396,9 +387,6 @@ async def call_post(
     logger.debug(f"Calling POST '{url}'")
     error_message = None
 
-    # Inject JWT from FastMCP context if available
-    headers = inject_auth_header(headers)
-
     try:
         response = await client.post(
             url=url,
@@ -481,9 +469,6 @@ async def call_delete(
     logger.debug(f"Calling DELETE '{url}'")
     error_message = None
 
-    # Inject JWT from FastMCP context if available
-    headers = inject_auth_header(headers)
-
     try:
         response = await client.delete(
             url=url,

basic_memory/mcp/tools/view_note.py

@@ -22,14 +22,10 @@ async def view_note(
 ) -> 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.
+    This tool reads a note using the same logic as read_note but instructs Claude
+    to display the content as a markdown artifact in the Claude Desktop app.
     Project parameter optional with server resolution.
 
-    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
         project: Project name to read from. Optional - server will resolve using hierarchy.
@@ -39,7 +35,7 @@ async def view_note(
         context: Optional FastMCP context for performance caching.
 
     Returns:
-        The note content as a markdown artifact with a confirmation message.
+        Instructions for Claude to create a markdown artifact with the note content.
 
     Examples:
         # View a note by title
@@ -66,26 +62,16 @@ async def view_note(
 
     # 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 content  # Return error message directly
 
+    # Return instructions for Claude to create an artifact
     return dedent(f"""
-            <instructions>
-            Create an artifact using the returned content to display the note in a readable format.
-            </instructions>
-            {artifact}\n\n✅ Note displayed as artifact: **{title}**""")
+        Note retrieved: "{identifier}"
+        
+        Display this note as a markdown artifact for the user.
+    
+        Content:
+        ---
+        {content}
+        ---
+        """).strip()

basic_memory/mcp/tools/write_note.py

@@ -4,7 +4,7 @@ from typing import List, Union, Optional
 
 from loguru import logger
 
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.project_context import get_active_project, add_project_metadata
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put
@@ -63,7 +63,8 @@ async def write_note(
         title: The title of the note
         content: Markdown content for the note, can include observations and relations
         folder: Folder path relative to project root where the file should be saved.
-                Use forward slashes (/) as separators. Examples: "notes", "projects/2025", "research/ml"
+                Use forward slashes (/) as separators. Use "/" or "" to write to project root.
+                Examples: "notes", "projects/2025", "research/ml", "/" (root)
         project: Project name to write to. Optional - server will resolve using the
                 hierarchy above. If unknown, use list_memory_projects() to discover
                 available projects.
@@ -117,92 +118,101 @@ async def write_note(
         HTTPError: If project doesn't exist or is inaccessible
         SecurityError: If folder path attempts path traversal
     """
-    logger.info(
-        f"MCP tool call tool=write_note project={project} folder={folder}, title={title}, tags={tags}"
-    )
-
-    # Get and validate the project (supports optional project parameter)
-    active_project = await get_active_project(client, project, context)
-
-    # Validate folder path to prevent path traversal attacks
-    project_path = active_project.home
-    if folder and not validate_project_path(folder, project_path):
-        logger.warning(
-            "Attempted path traversal attack blocked", folder=folder, project=active_project.name
+    async with get_client() as client:
+        logger.info(
+            f"MCP tool call tool=write_note project={project} folder={folder}, title={title}, tags={tags}"
         )
-        return f"# Error\n\nFolder path '{folder}' is not allowed - paths must stay within project boundaries"
-
-    # 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, 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."
-
-    # Process tags using the helper function
-    tag_list = parse_tags(tags)
-    # Create the entity request
-    metadata = {"tags": tag_list} if tag_list else None
-    entity = Entity(
-        title=title,
-        folder=folder,
-        entity_type=entity_type,
-        content_type="text/markdown",
-        content=content,
-        entity_metadata=metadata,
-    )
-    project_url = active_project.permalink
-
-    # Create or update via knowledge API
-    logger.debug(f"Creating entity via API permalink={entity.permalink}")
-    url = f"{project_url}/knowledge/entities/{entity.permalink}"
-    response = await call_put(client, url, json=entity.model_dump())
-    result = EntityResponse.model_validate(response.json())
-
-    # Format semantic summary based on status code
-    action = "Created" if response.status_code == 201 else "Updated"
-    summary = [
-        f"# {action} note",
-        f"project: {active_project.name}",
-        f"file_path: {result.file_path}",
-        f"permalink: {result.permalink}",
-        f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
-    ]
-
-    # Count observations by category
-    categories = {}
-    if result.observations:
-        for obs in result.observations:
-            categories[obs.category] = categories.get(obs.category, 0) + 1
-
-        summary.append("\n## Observations")
-        for category, count in sorted(categories.items()):
-            summary.append(f"- {category}: {count}")
-
-    # Count resolved/unresolved relations
-    unresolved = 0
-    resolved = 0
-    if result.relations:
-        unresolved = sum(1 for r in result.relations if not r.to_id)
-        resolved = len(result.relations) - unresolved
-
-        summary.append("\n## Relations")
-        summary.append(f"- Resolved: {resolved}")
-        if unresolved:
-            summary.append(f"- Unresolved: {unresolved}")
-            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."
+
+        # Get and validate the project (supports optional project parameter)
+        active_project = await get_active_project(client, project, context)
+
+        # Normalize "/" to empty string for root folder (must happen before validation)
+        if folder == "/":
+            folder = ""
+
+        # Validate folder path to prevent path traversal attacks
+        project_path = active_project.home
+        if folder and not validate_project_path(folder, project_path):
+            logger.warning(
+                "Attempted path traversal attack blocked",
+                folder=folder,
+                project=active_project.name,
             )
+            return f"# Error\n\nFolder path '{folder}' is not allowed - paths must stay within project boundaries"
 
-    if tag_list:
-        summary.append(f"\n## Tags\n- {', '.join(tag_list)}")
+        # Check migration status and wait briefly if needed
+        from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
 
-    # Log the response with structured data
-    logger.info(
-        f"MCP tool response: tool=write_note project={active_project.name} action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved} status_code={response.status_code}"
-    )
-    result = "\n".join(summary)
-    return add_project_metadata(result, active_project.name)
+        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."
+
+        # Process tags using the helper function
+        tag_list = parse_tags(tags)
+        # Create the entity request
+        metadata = {"tags": tag_list} if tag_list else None
+        entity = Entity(
+            title=title,
+            folder=folder,
+            entity_type=entity_type,
+            content_type="text/markdown",
+            content=content,
+            entity_metadata=metadata,
+        )
+        project_url = active_project.permalink
+
+        # Create or update via knowledge API
+        logger.debug(f"Creating entity via API permalink={entity.permalink}")
+        url = f"{project_url}/knowledge/entities/{entity.permalink}"
+        response = await call_put(client, url, json=entity.model_dump())
+        result = EntityResponse.model_validate(response.json())
+
+        # Format semantic summary based on status code
+        action = "Created" if response.status_code == 201 else "Updated"
+        summary = [
+            f"# {action} note",
+            f"project: {active_project.name}",
+            f"file_path: {result.file_path}",
+            f"permalink: {result.permalink}",
+            f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+        ]
+
+        # Count observations by category
+        categories = {}
+        if result.observations:
+            for obs in result.observations:
+                categories[obs.category] = categories.get(obs.category, 0) + 1
+
+            summary.append("\n## Observations")
+            for category, count in sorted(categories.items()):
+                summary.append(f"- {category}: {count}")
+
+        # Count resolved/unresolved relations
+        unresolved = 0
+        resolved = 0
+        if result.relations:
+            unresolved = sum(1 for r in result.relations if not r.to_id)
+            resolved = len(result.relations) - unresolved
+
+            summary.append("\n## Relations")
+            summary.append(f"- Resolved: {resolved}")
+            if unresolved:
+                summary.append(f"- Unresolved: {unresolved}")
+                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)}")
+
+        # Log the response with structured data
+        logger.info(
+            f"MCP tool response: tool=write_note project={active_project.name} action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved} status_code={response.status_code}"
+        )
+        result = "\n".join(summary)
+        return add_project_metadata(result, active_project.name)