basic-memory 0.16.1__py3-none-any.whl → 0.17.4__py3-none-any.whl

basic_memory/mcp/tools/canvas.py

@@ -12,7 +12,8 @@ from fastmcp import Context
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_put
+from basic_memory.mcp.tools.utils import call_put, call_post, resolve_entity_id
+from basic_memory.telemetry import track_mcp_tool
 
 
 @mcp.tool(
@@ -94,9 +95,9 @@ async def canvas(
     Raises:
         ToolError: If project doesn't exist or folder path is invalid
     """
+    track_mcp_tool("canvas")
     async with get_client() as client:
         active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
 
         # Ensure path has .canvas extension
         file_title = title if title.endswith(".canvas") else f"{title}.canvas"
@@ -108,23 +109,44 @@ async def canvas(
         # Convert to JSON
         canvas_json = json.dumps(canvas_data, indent=2)
 
-        # Write the file using the resource API
+        # Try to create the canvas file first (optimistic create)
         logger.info(f"Creating canvas file: {file_path} in project {project}")
-        # Send canvas_json as content string, not as json parameter
-        # The resource endpoint expects Body() string content, not JSON-encoded data
-        response = await call_put(
-            client,
-            f"{project_url}/resource/{file_path}",
-            content=canvas_json,
-            headers={"Content-Type": "text/plain"},
-        )
+        try:
+            response = await call_post(
+                client,
+                f"/v2/projects/{active_project.external_id}/resource",
+                json={"file_path": file_path, "content": canvas_json},
+            )
+            action = "Created"
+        except Exception as e:
+            # If creation failed due to conflict (already exists), try to update
+            if (
+                "409" in str(e)
+                or "conflict" in str(e).lower()
+                or "already exists" in str(e).lower()
+            ):
+                logger.info(f"Canvas file exists, updating instead: {file_path}")
+                try:
+                    entity_id = await resolve_entity_id(client, active_project.external_id, file_path)
+                    # For update, send content in JSON body
+                    response = await call_put(
+                        client,
+                        f"/v2/projects/{active_project.external_id}/resource/{entity_id}",
+                        json={"content": canvas_json},
+                    )
+                    action = "Updated"
+                except Exception as update_error:  # pragma: no cover
+                    # Re-raise the original error if update also fails
+                    raise e from update_error  # pragma: no cover
+            else:
+                # Re-raise if it's not a conflict error
+                raise  # pragma: no cover
 
         # Parse response
         result = response.json()
         logger.debug(result)
 
         # Build summary
-        action = "Created" if response.status_code == 201 else "Updated"
         summary = [f"# {action}: {file_path}", "\nThe canvas is ready to open in Obsidian."]
 
         return "\n".join(summary)

basic_memory/mcp/tools/chatgpt_tools.py

@@ -15,6 +15,7 @@ from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.read_note import read_note
 from basic_memory.schemas.search import SearchResponse
 from basic_memory.config import ConfigManager
+from basic_memory.telemetry import track_mcp_tool
 
 
 def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str, Any]]:
@@ -55,7 +56,7 @@ def _format_document_for_chatgpt(
         title = "Untitled Document"
 
     # Handle error cases
-    if isinstance(content, str) and content.startswith("# Note Not Found"):
+    if isinstance(content, str) and content.lstrip().startswith("# Note Not Found"):
         return {
             "id": identifier,
             "title": title or "Document Not Found",
@@ -88,6 +89,7 @@ async def search(
         List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
         where the JSON body contains `results`, `total_count`, and echo of `query`.
     """
+    track_mcp_tool("search")
     logger.info(f"ChatGPT search request: query='{query}'")
 
     try:
@@ -151,6 +153,7 @@ async def fetch(
         List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
         where the JSON body includes `id`, `title`, `text`, `url`, and metadata.
     """
+    track_mcp_tool("fetch")
     logger.info(f"ChatGPT fetch request: id='{id}'")
 
     try:

basic_memory/mcp/tools/delete_note.py

@@ -3,12 +3,12 @@ from typing import Optional
 
 from loguru import logger
 from fastmcp import Context
+from mcp.server.fastmcp.exceptions import ToolError
 
 from basic_memory.mcp.project_context import get_active_project
-from basic_memory.mcp.tools.utils import call_delete
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.async_client import get_client
-from basic_memory.schemas import DeleteEntitiesResponse
+from basic_memory.telemetry import track_mcp_tool
 
 
 def _format_delete_error_response(project: str, error_message: str, identifier: str) -> str:
@@ -202,13 +202,35 @@ async def delete_note(
         with suggestions for finding the correct identifier, including search
         commands and alternative formats to try.
     """
+    track_mcp_tool("delete_note")
     async with get_client() as client:
         active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
+
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import KnowledgeClient
+
+        # Use typed KnowledgeClient for API calls
+        knowledge_client = KnowledgeClient(client, active_project.external_id)
 
         try:
-            response = await call_delete(client, f"{project_url}/knowledge/entities/{identifier}")
-            result = DeleteEntitiesResponse.model_validate(response.json())
+            # Resolve identifier to entity ID
+            entity_id = await knowledge_client.resolve_entity(identifier)
+        except ToolError as e:
+            # If entity not found, return False (note doesn't exist)
+            if "Entity not found" in str(e) or "not found" in str(e).lower():
+                logger.warning(f"Note not found for deletion: {identifier}")
+                return False
+            # For other resolution errors, return formatted error message
+            logger.error(  # pragma: no cover
+                f"Delete failed for '{identifier}': {e}, project: {active_project.name}"
+            )
+            return _format_delete_error_response(  # pragma: no cover
+                active_project.name, str(e), identifier
+            )
+
+        try:
+            # Call the DELETE endpoint
+            result = await knowledge_client.delete_entity(entity_id)
 
             if result.deleted:
                 logger.info(
@@ -216,8 +238,10 @@ async def delete_note(
                 )
                 return True
             else:
-                logger.warning(f"Delete operation completed but note was not deleted: {identifier}")
-                return False
+                logger.warning(  # pragma: no cover
+                    f"Delete operation completed but note was not deleted: {identifier}"
+                )
+                return False  # pragma: no cover
 
         except Exception as e:  # pragma: no cover
             logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")

basic_memory/mcp/tools/edit_note.py

@@ -8,8 +8,7 @@ from fastmcp import Context
 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_patch
-from basic_memory.schemas import EntityResponse
+from basic_memory.telemetry import track_mcp_tool
 
 
 def _format_error_response(
@@ -214,9 +213,9 @@ async def edit_note(
         search_notes() first to find the correct identifier. The tool provides detailed
         error messages with suggestions if operations fail.
     """
+    track_mcp_tool("edit_note")
     async with get_client() as client:
         active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
 
         logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation)
 
@@ -235,6 +234,15 @@ async def edit_note(
 
         # Use the PATCH endpoint to edit the entity
         try:
+            # Import here to avoid circular import
+            from basic_memory.mcp.clients import KnowledgeClient
+
+            # Use typed KnowledgeClient for API calls
+            knowledge_client = KnowledgeClient(client, active_project.external_id)
+
+            # Resolve identifier to entity ID
+            entity_id = await knowledge_client.resolve_entity(identifier)
+
             # Prepare the edit request data
             edit_data = {
                 "operation": operation,
@@ -250,9 +258,7 @@ async def edit_note(
                 edit_data["expected_replacements"] = str(expected_replacements)
 
             # Call the PATCH endpoint
-            url = f"{project_url}/knowledge/entities/{identifier}"
-            response = await call_patch(client, url, json=edit_data)
-            result = EntityResponse.model_validate(response.json())
+            result = await knowledge_client.patch_entity(entity_id, edit_data)
 
             # Format summary
             summary = [
@@ -307,11 +313,10 @@ async def edit_note(
                 permalink=result.permalink,
                 observations_count=len(result.observations),
                 relations_count=len(result.relations),
-                status_code=response.status_code,
             )
 
-            result = "\n".join(summary)
-            return add_project_metadata(result, active_project.name)
+            summary_result = "\n".join(summary)
+            return add_project_metadata(summary_result, active_project.name)
 
         except Exception as e:
             logger.error(f"Error editing note: {e}")

basic_memory/mcp/tools/list_directory.py

@@ -8,7 +8,7 @@ from fastmcp import Context
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_get
+from basic_memory.telemetry import track_mcp_tool
 
 
 @mcp.tool(
@@ -63,30 +63,20 @@ async def list_directory(
     Raises:
         ToolError: If project doesn't exist or directory path is invalid
     """
+    track_mcp_tool("list_directory")
     async with get_client() as client:
         active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
-
-        # Prepare query parameters
-        params = {
-            "dir_name": dir_name,
-            "depth": str(depth),
-        }
-        if file_name_glob:
-            params["file_name_glob"] = file_name_glob
 
         logger.debug(
             f"Listing directory '{dir_name}' in project {project} with depth={depth}, glob='{file_name_glob}'"
         )
 
-        # Call the API endpoint
-        response = await call_get(
-            client,
-            f"{project_url}/directory/list",
-            params=params,
-        )
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import DirectoryClient
 
-        nodes = response.json()
+        # Use typed DirectoryClient for API calls
+        directory_client = DirectoryClient(client, active_project.external_id)
+        nodes = await directory_client.list(dir_name, depth=depth, file_name_glob=file_name_glob)
 
         if not nodes:
             filter_desc = ""

basic_memory/mcp/tools/move_note.py

@@ -8,10 +8,8 @@ from fastmcp import Context
 
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_post, call_get
 from basic_memory.mcp.project_context import get_active_project
-from basic_memory.schemas import EntityResponse
-from basic_memory.schemas.project_info import ProjectList
+from basic_memory.telemetry import track_mcp_tool
 from basic_memory.utils import validate_project_path
 
 
@@ -30,9 +28,12 @@ async def _detect_cross_project_move_attempt(
         Error message with guidance if cross-project move is detected, None otherwise
     """
     try:
-        # Get list of all available projects to check against
-        response = await call_get(client, "/projects/projects")
-        project_list = ProjectList.model_validate(response.json())
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import ProjectClient
+
+        # Use typed ProjectClient for API calls
+        project_client = ProjectClient(client)
+        project_list = await project_client.list_projects()
         project_names = [p.name.lower() for p in project_list.projects]
 
         # Check if destination path contains any project names
@@ -104,11 +105,12 @@ def _format_potential_cross_project_guidance(
     identifier: str, destination_path: str, current_project: str, available_projects: list[str]
 ) -> str:
     """Format guidance for potentially cross-project moves."""
-    other_projects = ", ".join(available_projects[:3])  # Show first 3 projects
-    if len(available_projects) > 3:
-        other_projects += f" (and {len(available_projects) - 3} others)"
+    other_projects = ", ".join(available_projects[:3])  # Show first 3 projects  # pragma: no cover
+    if len(available_projects) > 3:  # pragma: no cover
+        other_projects += f" (and {len(available_projects) - 3} others)"  # pragma: no cover
 
-    return dedent(f"""
+    return (  # pragma: no cover
+        dedent(f"""
         # Move Failed - Check Project Context
         
         Cannot move '{identifier}' to '{destination_path}' within the current project '{current_project}'.
@@ -139,6 +141,7 @@ def _format_potential_cross_project_guidance(
         list_memory_projects()
         ```
         """).strip()
+    )
 
 
 def _format_move_error_response(error_message: str, identifier: str, destination_path: str) -> str:
@@ -302,9 +305,10 @@ delete_note("{identifier}")
 ```"""
 
     # Generic fallback
-    return f"""# Move Failed
+    return (  # pragma: no cover
+        f"""# Move Failed
 
-Error moving '{identifier}' to '{destination_path}': {error_message}
+Error moving '{identifier}' to '{destination_path}': {error_message}  # pragma: no cover
 
 ## General troubleshooting:
 1. **Verify the note exists**: `read_note("{identifier}")` or `search_notes("{identifier}")`
@@ -335,6 +339,7 @@ write_note("Title", content, "target-folder")
 # Delete original once confirmed
 delete_note("{identifier}")
 ```"""
+    )
 
 
 @mcp.tool(
@@ -395,11 +400,11 @@ async def move_note(
     - Re-indexes the entity for search
     - Maintains all observations and relations
     """
+    track_mcp_tool("move_note")
     async with get_client() as client:
         logger.debug(f"Moving note: {identifier} to {destination_path} in project: {project}")
 
         active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
 
         # Validate destination path to prevent path traversal attacks
         project_path = active_project.home
@@ -431,13 +436,19 @@ move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in dest
             logger.info(f"Detected cross-project move attempt: {identifier} -> {destination_path}")
             return cross_project_error
 
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import KnowledgeClient
+
+        # Use typed KnowledgeClient for API calls
+        knowledge_client = KnowledgeClient(client, active_project.external_id)
+
         # Get the source entity information for extension validation
         source_ext = "md"  # Default to .md if we can't determine source extension
         try:
+            # Resolve identifier to entity ID
+            entity_id = await knowledge_client.resolve_entity(identifier)
             # Fetch source entity information to get the current file extension
-            url = f"{project_url}/knowledge/entities/{identifier}"
-            response = await call_get(client, url)
-            source_entity = EntityResponse.model_validate(response.json())
+            source_entity = await knowledge_client.get_entity(entity_id)
             if "." in source_entity.file_path:
                 source_ext = source_entity.file_path.split(".")[-1]
         except Exception as e:
@@ -467,10 +478,10 @@ move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in dest
 
         # Get the source entity to check its file extension
         try:
+            # Resolve identifier to entity ID (might already be cached from above)
+            entity_id = await knowledge_client.resolve_entity(identifier)
             # Fetch source entity information
-            url = f"{project_url}/knowledge/entities/{identifier}"
-            response = await call_get(client, url)
-            source_entity = EntityResponse.model_validate(response.json())
+            source_entity = await knowledge_client.get_entity(entity_id)
 
             # Extract file extensions
             source_ext = (
@@ -505,17 +516,11 @@ move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in dest
             logger.debug(f"Could not fetch source entity for extension check: {e}")
 
         try:
-            # Prepare move request
-            move_data = {
-                "identifier": identifier,
-                "destination_path": destination_path,
-                "project": active_project.name,
-            }
-
-            # Call the move API endpoint
-            url = f"{project_url}/knowledge/move"
-            response = await call_post(client, url, json=move_data)
-            result = EntityResponse.model_validate(response.json())
+            # Resolve identifier to entity ID for the move operation
+            entity_id = await knowledge_client.resolve_entity(identifier)
+
+            # Call the move API using KnowledgeClient
+            result = await knowledge_client.move_entity(entity_id, destination_path)
 
             # Build success message
             result_lines = [
@@ -534,7 +539,6 @@ move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in dest
                 identifier=identifier,
                 destination_path=destination_path,
                 project=active_project.name,
-                status_code=response.status_code,
             )
 
             return "\n".join(result_lines)

basic_memory/mcp/tools/project_management.py

@@ -9,12 +9,8 @@ from fastmcp import Context
 
 from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_get, call_post, call_delete
-from basic_memory.schemas.project_info import (
-    ProjectList,
-    ProjectStatusResponse,
-    ProjectInfoRequest,
-)
+from basic_memory.schemas.project_info import ProjectInfoRequest
+from basic_memory.telemetry import track_mcp_tool
 from basic_memory.utils import generate_permalink
 
 
@@ -40,6 +36,7 @@ async def list_memory_projects(context: Context | None = None) -> str:
     Example:
         list_memory_projects()
     """
+    track_mcp_tool("list_memory_projects")
     async with get_client() as client:
         if context:  # pragma: no cover
             await context.info("Listing all available projects")
@@ -47,9 +44,12 @@ async def list_memory_projects(context: Context | None = None) -> str:
         # Check if server is constrained to a specific project
         constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
 
-        # Get projects from API
-        response = await call_get(client, "/projects/projects")
-        project_list = ProjectList.model_validate(response.json())
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import ProjectClient
+
+        # Use typed ProjectClient for API calls
+        project_client = ProjectClient(client)
+        project_list = await project_client.list_projects()
 
         if constrained_project:
             result = f"Project: {constrained_project}\n\n"
@@ -92,6 +92,7 @@ async def create_memory_project(
         create_memory_project("my-research", "~/Documents/research")
         create_memory_project("work-notes", "/home/user/work", set_default=True)
     """
+    track_mcp_tool("create_memory_project")
     async with get_client() as client:
         # Check if server is constrained to a specific project
         constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
@@ -106,9 +107,12 @@ async def create_memory_project(
             name=project_name, path=project_path, set_default=set_default
         )
 
-        # Call API to create project
-        response = await call_post(client, "/projects/projects", json=project_request.model_dump())
-        status_response = ProjectStatusResponse.model_validate(response.json())
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import ProjectClient
+
+        # Use typed ProjectClient for API calls
+        project_client = ProjectClient(client)
+        status_response = await project_client.create_project(project_request.model_dump())
 
         result = f"✓ {status_response.message}\n\n"
 
@@ -147,6 +151,7 @@ async def delete_project(project_name: str, context: Context | None = None) -> s
         This action cannot be undone. The project will need to be re-added
         to access its content through Basic Memory again.
     """
+    track_mcp_tool("delete_project")
     async with get_client() as client:
         # Check if server is constrained to a specific project
         constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
@@ -156,11 +161,18 @@ async def delete_project(project_name: str, context: Context | None = None) -> s
         if context:  # pragma: no cover
             await context.info(f"Deleting project: {project_name}")
 
+        # Import here to avoid circular import
+        from basic_memory.mcp.clients import ProjectClient
+
+        # Use typed ProjectClient for API calls
+        project_client = ProjectClient(client)
+
         # Get project info before deletion to validate it exists
-        response = await call_get(client, "/projects/projects")
-        project_list = ProjectList.model_validate(response.json())
+        project_list = await project_client.list_projects()
 
-        # Find the project by name (case-insensitive) or permalink - same logic as switch_project
+        # Find the project by permalink (derived from name).
+        # Note: The API response uses `ProjectItem` which derives `permalink` from `name`,
+        # so a separate case-insensitive name match would be redundant here.
         project_permalink = generate_permalink(project_name)
         target_project = None
         for p in project_list.projects:
@@ -168,10 +180,6 @@ async def delete_project(project_name: str, context: Context | None = None) -> s
             if p.permalink == project_permalink:
                 target_project = p
                 break
-            # Also match by name comparison (case-insensitive)
-            if p.name.lower() == project_name.lower():
-                target_project = p
-                break
 
         if not target_project:
             available_projects = [p.name for p in project_list.projects]
@@ -179,12 +187,8 @@ async def delete_project(project_name: str, context: Context | None = None) -> s
                 f"Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
             )
 
-        # Call API to delete project using URL encoding for special characters
-        from urllib.parse import quote
-
-        encoded_name = quote(target_project.name, safe="")
-        response = await call_delete(client, f"/projects/{encoded_name}")
-        status_response = ProjectStatusResponse.model_validate(response.json())
+        # Delete project using project external_id
+        status_response = await project_client.delete_project(target_project.external_id)
 
         result = f"✓ {status_response.message}\n\n"
 

basic_memory/mcp/tools/read_content.py

@@ -13,12 +13,14 @@ from typing import Optional
 from loguru import logger
 from PIL import Image as PILImage
 from fastmcp import Context
+from mcp.server.fastmcp.exceptions import ToolError
 
 from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.async_client import get_client
-from basic_memory.mcp.tools.utils import call_get
+from basic_memory.mcp.tools.utils import call_get, resolve_entity_id
 from basic_memory.schemas.memory import memory_url_path
+from basic_memory.telemetry import track_mcp_tool
 from basic_memory.utils import validate_project_path
 
 
@@ -199,11 +201,11 @@ async def read_content(
         HTTPError: If project doesn't exist or is inaccessible
         SecurityError: If path attempts path traversal
     """
+    track_mcp_tool("read_content")
     logger.info("Reading file", path=path, project=project)
 
     async with get_client() as client:
         active_project = await get_active_project(client, project, context)
-        project_url = active_project.project_url
 
         url = memory_url_path(path)
 
@@ -221,7 +223,15 @@ async def read_content(
                 "error": f"Path '{path}' is not allowed - paths must stay within project boundaries",
             }
 
-        response = await call_get(client, f"{project_url}/resource/{url}")
+        # Resolve path to entity ID
+        try:
+            entity_id = await resolve_entity_id(client, active_project.external_id, url)
+        except ToolError:
+            # Convert resolution errors to "Resource not found" for consistency
+            raise ToolError(f"Resource not found: {url}")
+
+        # Call the v2 resource endpoint
+        response = await call_get(client, f"/v2/projects/{active_project.external_id}/resource/{entity_id}")
         content_type = response.headers.get("content-type", "application/octet-stream")
         content_length = int(response.headers.get("content-length", 0))