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

basic_memory/mcp/tools/build_context.py

@@ -0,0 +1,120 @@
+"""Build context tool for Basic Memory MCP server."""
+
+from typing import Optional
+
+from loguru import logger
+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.schemas.base import TimeFrame
+from basic_memory.schemas.memory import (
+    GraphContext,
+    MemoryUrl,
+    memory_url_path,
+)
+
+
+@mcp.tool(
+    description="""Build context from a memory:// URI to continue conversations naturally.
+
+    Use this to follow up on previous discussions or explore related topics.
+
+    Memory URL Format:
+    - Use paths like "folder/note" or "memory://folder/note"
+    - Pattern matching: "folder/*" matches all notes in folder
+    - Valid characters: letters, numbers, hyphens, underscores, forward slashes
+    - Avoid: double slashes (//), angle brackets (<>), quotes, pipes (|)
+    - Examples: "specs/search", "projects/basic-memory", "notes/*"
+
+    Timeframes support natural language like:
+    - "2 days ago", "last week", "today", "3 months ago"
+    - Or standard formats like "7d", "24h"
+    """,
+)
+async def build_context(
+    url: MemoryUrl,
+    project: Optional[str] = None,
+    depth: str | int | None = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+    context: Context | None = None,
+) -> GraphContext:
+    """Get context needed to continue a discussion within a specific project.
+
+    This tool enables natural continuation of discussions by loading relevant context
+    from memory:// URIs. It uses pattern matching to find relevant content and builds
+    a rich context graph of related information.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
+    Args:
+        project: Project name to build context from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        url: memory:// URI pointing to discussion content (e.g. memory://specs/search)
+        depth: How many relation hops to traverse (1-3 recommended for performance)
+        timeframe: How far back to look. Supports natural language like "2 days ago", "last week"
+        page: Page number of results to return (default: 1)
+        page_size: Number of results to return per page (default: 10)
+        max_related: Maximum number of related results to return (default: 10)
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        GraphContext containing:
+            - primary_results: Content matching the memory:// URI
+            - related_results: Connected content via relations
+            - metadata: Context building details
+
+    Examples:
+        # Continue a specific discussion
+        build_context("my-project", "memory://specs/search")
+
+        # Get deeper context about a component
+        build_context("work-docs", "memory://components/memory-service", depth=2)
+
+        # Look at recent changes to a specification
+        build_context("research", "memory://specs/document-format", timeframe="today")
+
+        # Research the history of a feature
+        build_context("dev-notes", "memory://features/knowledge-graph", timeframe="3 months ago")
+
+    Raises:
+        ToolError: If project doesn't exist or depth parameter is invalid
+    """
+    logger.info(f"Building context from {url} in project {project}")
+
+    # Convert string depth to integer if needed
+    if isinstance(depth, str):
+        try:
+            depth = int(depth)
+        except ValueError:
+            from mcp.server.fastmcp.exceptions import ToolError
+
+            raise ToolError(f"Invalid depth parameter: '{depth}' is not a valid integer")
+
+    # URL is already validated and normalized by MemoryUrl type annotation
+
+    async with get_client() as client:
+        # Get the active project using the new stateless approach
+        active_project = await get_active_project(client, project, context)
+
+        project_url = active_project.project_url
+
+        response = await call_get(
+            client,
+            f"{project_url}/memory/{memory_url_path(url)}",
+            params={
+                "depth": depth,
+                "timeframe": timeframe,
+                "page": page,
+                "page_size": page_size,
+                "max_related": max_related,
+            },
+        )
+        return GraphContext.model_validate(response.json())

basic_memory/mcp/tools/canvas.py

@@ -0,0 +1,130 @@
+"""Canvas creation tool for Basic Memory MCP server.
+
+This tool creates Obsidian canvas files (.canvas) using the JSON Canvas 1.0 spec.
+"""
+
+import json
+from typing import Dict, List, Any, Optional
+
+from loguru import logger
+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
+
+
+@mcp.tool(
+    description="Create an Obsidian canvas file to visualize concepts and connections.",
+)
+async def canvas(
+    nodes: List[Dict[str, Any]],
+    edges: List[Dict[str, Any]],
+    title: str,
+    folder: str,
+    project: Optional[str] = None,
+    context: Context | None = None,
+) -> str:
+    """Create an Obsidian canvas file with the provided nodes and edges.
+
+    This tool creates a .canvas file compatible with Obsidian's Canvas feature,
+    allowing visualization of relationships between concepts or documents.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
+    For the full JSON Canvas 1.0 specification, see the 'spec://canvas' resource.
+
+    Args:
+        project: Project name to create canvas in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        nodes: List of node objects following JSON Canvas 1.0 spec
+        edges: List of edge objects following JSON Canvas 1.0 spec
+        title: The title of the canvas (will be saved as title.canvas)
+        folder: Folder path relative to project root where the canvas should be saved.
+                Use forward slashes (/) as separators. Examples: "diagrams", "projects/2025", "visual/maps"
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        A summary of the created canvas file
+
+    Important Notes:
+    - When referencing files, use the exact file path as shown in Obsidian
+      Example: "folder/Document Name.md" (not permalink format)
+    - For file nodes, the "file" attribute must reference an existing file
+    - Nodes require id, type, x, y, width, height properties
+    - Edges require id, fromNode, toNode properties
+    - Position nodes in a logical layout (x,y coordinates in pixels)
+    - Use color attributes ("1"-"6" or hex) for visual organization
+
+    Basic Structure:
+    ```json
+    {
+      "nodes": [
+        {
+          "id": "node1",
+          "type": "file",  // Options: "file", "text", "link", "group"
+          "file": "folder/Document.md",
+          "x": 0,
+          "y": 0,
+          "width": 400,
+          "height": 300
+        }
+      ],
+      "edges": [
+        {
+          "id": "edge1",
+          "fromNode": "node1",
+          "toNode": "node2",
+          "label": "connects to"
+        }
+      ]
+    }
+    ```
+
+    Examples:
+        # Create canvas in project
+        canvas("my-project", nodes=[...], edges=[...], title="My Canvas", folder="diagrams")
+
+        # Create canvas in work project
+        canvas("work-project", nodes=[...], edges=[...], title="Process Flow", folder="visual/maps")
+
+    Raises:
+        ToolError: If project doesn't exist or folder path is invalid
+    """
+    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"
+        file_path = f"{folder}/{file_title}"
+
+        # Create canvas data structure
+        canvas_data = {"nodes": nodes, "edges": edges}
+
+        # Convert to JSON
+        canvas_json = json.dumps(canvas_data, indent=2)
+
+        # Write the file using the resource API
+        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"},
+        )
+
+        # 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

@@ -0,0 +1,187 @@
+"""ChatGPT-compatible MCP tools for Basic Memory.
+
+These adapters expose Basic Memory's search/fetch functionality using the exact
+tool names and response structure OpenAI's MCP clients expect: each call returns
+a list containing a single `{"type": "text", "text": "{...json...}"}` item.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.server import mcp
+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
+
+
+def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str, Any]]:
+    """Format search results according to ChatGPT's expected schema.
+
+    Returns a list of result objects with id, title, and url fields.
+    """
+    formatted_results = []
+
+    for result in results.results:
+        formatted_result = {
+            "id": result.permalink or f"doc-{len(formatted_results)}",
+            "title": result.title if result.title and result.title.strip() else "Untitled",
+            "url": result.permalink or "",
+        }
+        formatted_results.append(formatted_result)
+
+    return formatted_results
+
+
+def _format_document_for_chatgpt(
+    content: str, identifier: str, title: Optional[str] = None
+) -> Dict[str, Any]:
+    """Format document content according to ChatGPT's expected schema.
+
+    Returns a document object with id, title, text, url, and metadata fields.
+    """
+    # Extract title from markdown content if not provided
+    if not title and isinstance(content, str):
+        lines = content.split("\n")
+        if lines and lines[0].startswith("# "):
+            title = lines[0][2:].strip()
+        else:
+            title = identifier.split("/")[-1].replace("-", " ").title()
+
+    # Ensure title is never None
+    if not title:
+        title = "Untitled Document"
+
+    # Handle error cases
+    if isinstance(content, str) and content.startswith("# Note Not Found"):
+        return {
+            "id": identifier,
+            "title": title or "Document Not Found",
+            "text": content,
+            "url": identifier,
+            "metadata": {"error": "Document not found"},
+        }
+
+    return {
+        "id": identifier,
+        "title": title or "Untitled Document",
+        "text": content,
+        "url": identifier,
+        "metadata": {"format": "markdown"},
+    }
+
+
+@mcp.tool(description="Search for content across the knowledge base")
+async def search(
+    query: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP search adapter returning a single text content item.
+
+    Args:
+        query: Search query (full-text syntax supported by `search_notes`)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body contains `results`, `total_count`, and echo of `query`.
+    """
+    logger.info(f"ChatGPT search request: query='{query}'")
+
+    try:
+        # ChatGPT tools don't expose project parameter, so use default project
+        config = ConfigManager().config
+        default_project = config.default_project
+
+        # Call underlying search_notes with sensible defaults for ChatGPT
+        results = await search_notes.fn(
+            query=query,
+            project=default_project,  # Use default project for ChatGPT
+            page=1,
+            page_size=10,  # Reasonable default for ChatGPT consumption
+            search_type="text",  # Default to full-text search
+            context=context,
+        )
+
+        # Handle string error responses from search_notes
+        if isinstance(results, str):
+            logger.warning(f"Search failed with error: {results[:100]}...")
+            search_results = {
+                "results": [],
+                "error": "Search failed",
+                "error_details": results[:500],  # Truncate long error messages
+            }
+        else:
+            # Format successful results for ChatGPT
+            formatted_results = _format_search_results_for_chatgpt(results)
+            search_results = {
+                "results": formatted_results,
+                "total_count": len(results.results),  # Use actual count from results
+                "query": query,
+            }
+            logger.info(f"Search completed: {len(formatted_results)} results returned")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(search_results, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT search failed for query '{query}': {e}")
+        error_results = {
+            "results": [],
+            "error": "Internal search error",
+            "error_message": str(e)[:200],
+        }
+        return [{"type": "text", "text": json.dumps(error_results, ensure_ascii=False)}]
+
+
+@mcp.tool(description="Fetch the full contents of a search result document")
+async def fetch(
+    id: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP fetch adapter returning a single text content item.
+
+    Args:
+        id: Document identifier (permalink, title, or memory URL)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body includes `id`, `title`, `text`, `url`, and metadata.
+    """
+    logger.info(f"ChatGPT fetch request: id='{id}'")
+
+    try:
+        # ChatGPT tools don't expose project parameter, so use default project
+        config = ConfigManager().config
+        default_project = config.default_project
+
+        # Call underlying read_note function
+        content = await read_note.fn(
+            identifier=id,
+            project=default_project,  # Use default project for ChatGPT
+            page=1,
+            page_size=10,  # Default pagination
+            context=context,
+        )
+
+        # Format the document for ChatGPT
+        document = _format_document_for_chatgpt(content, id)
+
+        logger.info(f"Fetch completed: id='{id}', content_length={len(document.get('text', ''))}")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(document, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT fetch failed for id '{id}': {e}")
+        error_document = {
+            "id": id,
+            "title": "Fetch Error",
+            "text": f"Failed to fetch document: {str(e)[:200]}",
+            "url": id,
+            "metadata": {"error": "Fetch failed"},
+        }
+        return [{"type": "text", "text": json.dumps(error_document, ensure_ascii=False)}]

basic_memory/mcp/tools/delete_note.py

@@ -0,0 +1,225 @@
+from textwrap import dedent
+from typing import Optional
+
+from loguru import logger
+from fastmcp import Context
+
+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
+
+
+def _format_delete_error_response(project: str, error_message: str, identifier: str) -> str:
+    """Format helpful error responses for delete failures that guide users to successful deletions."""
+
+    # Note not found errors
+    if "entity not found" in error_message.lower() or "not found" in error_message.lower():
+        search_term = identifier.split("/")[-1] if "/" in identifier else identifier
+        title_format = (
+            identifier.split("/")[-1].replace("-", " ").title() if "/" in identifier else identifier
+        )
+        permalink_format = identifier.lower().replace(" ", "-")
+
+        return dedent(f"""
+            # Delete Failed - Note Not Found
+
+            The note '{identifier}' could not be found for deletion in {project}.
+
+            ## This might mean:
+            1. **Already deleted**: The note may have been deleted previously
+            2. **Wrong identifier**: The identifier format might be incorrect
+            3. **Different project**: The note might be in a different project
+
+            ## How to verify:
+            1. **Search for the note**: Use `search_notes("{project}", "{search_term}")` to find it
+            2. **Try different formats**:
+               - If you used a permalink like "folder/note-title", try just the title: "{title_format}"
+               - If you used a title, try the permalink format: "{permalink_format}"
+
+            3. **Check if already deleted**: Use `list_directory("/")` to see what notes exist
+            4. **List notes in project**: Use `list_directory("/")` to see what notes exist in the current project
+
+            ## If the note actually exists:
+            ```
+            # First, find the correct identifier:
+            search_notes("{project}", "{identifier}")
+
+            # Then delete using the correct identifier:
+            delete_note("{project}", "correct-identifier-from-search")
+            ```
+
+            ## If you want to delete multiple similar notes:
+            Use search to find all related notes and delete them one by one.
+            """).strip()
+
+    # Permission/access errors
+    if (
+        "permission" in error_message.lower()
+        or "access" in error_message.lower()
+        or "forbidden" in error_message.lower()
+    ):
+        return f"""# Delete Failed - Permission Error
+
+You don't have permission to delete '{identifier}': {error_message}
+
+## How to resolve:
+1. **Check permissions**: Verify you have delete/write access to this project
+2. **File locks**: The note might be open in another application
+3. **Project access**: Ensure you're in the correct project with proper permissions
+
+## Alternative actions:
+- List available projects: `list_memory_projects()`
+- Specify the correct project: `delete_note("{identifier}", project="project-name")`
+- Verify note exists first: `read_note("{identifier}", project="project-name")`
+
+## If you have read-only access:
+Ask someone with write access to delete the note."""
+
+    # Server/filesystem errors
+    if (
+        "server error" in error_message.lower()
+        or "filesystem" in error_message.lower()
+        or "disk" in error_message.lower()
+    ):
+        return f"""# Delete Failed - System Error
+
+A system error occurred while deleting '{identifier}': {error_message}
+
+## Immediate steps:
+1. **Try again**: The error might be temporary
+2. **Check file status**: Verify the file isn't locked or in use
+3. **Check disk space**: Ensure the system has adequate storage
+
+## Troubleshooting:
+- Verify note exists: `read_note("{project}","{identifier}")`
+- Try again in a few moments
+
+## If problem persists:
+Send a message to support@basicmachines.co - there may be a filesystem or database issue."""
+
+    # Database/sync errors
+    if "database" in error_message.lower() or "sync" in error_message.lower():
+        return f"""# Delete Failed - Database Error
+
+A database error occurred while deleting '{identifier}': {error_message}
+
+## This usually means:
+1. **Sync conflict**: The file system and database are out of sync
+2. **Database lock**: Another operation is accessing the database
+3. **Corrupted entry**: The database entry might be corrupted
+
+## Steps to resolve:
+1. **Try again**: Wait a moment and retry the deletion
+2. **Check note status**: `read_note("{project}","{identifier}")` to see current state
+3. **Manual verification**: Use `list_directory()` to see if file still exists
+
+## If the note appears gone but database shows it exists:
+Send a message to support@basicmachines.co - a manual database cleanup may be needed."""
+
+    # Generic fallback
+    return f"""# Delete Failed
+
+Error deleting note '{identifier}': {error_message}
+
+## General troubleshooting:
+1. **Verify the note exists**: `read_note("{project}", "{identifier}")` or `search_notes("{project}", "{identifier}")`
+2. **Check permissions**: Ensure you can edit/delete files in this project
+3. **Try again**: The error might be temporary
+4. **Check project**: Make sure you're in the correct project
+
+## Step-by-step approach:
+```
+# 1. Confirm note exists and get correct identifier
+search_notes("{project}", "{identifier}")
+
+# 2. Read the note to verify access
+read_note("{project}", "correct-identifier-from-search")
+
+# 3. Try deletion with correct identifier
+delete_note("{project}", "correct-identifier-from-search")
+```
+
+## Alternative approaches:
+- Check what notes exist: `list_directory("{project}", "/")`
+
+## Need help?
+If the note should be deleted but the operation keeps failing, send a message to support@basicmemory.com."""
+
+
+@mcp.tool(description="Delete a note by title or permalink")
+async def delete_note(
+    identifier: str, project: Optional[str] = None, context: Context | None = None
+) -> bool | str:
+    """Delete a note from the knowledge base.
+
+    Permanently removes a note from the specified project. The note is identified
+    by title or permalink. If the note doesn't exist, the operation returns False
+    without error. If deletion fails due to other issues, helpful error messages are provided.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
+    Args:
+        project: Project name to delete from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        identifier: Note title or permalink to delete
+                   Can be a title like "Meeting Notes" or permalink like "notes/meeting-notes"
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        True if note was successfully deleted, False if note was not found.
+        On errors, returns a formatted string with helpful troubleshooting guidance.
+
+    Examples:
+        # Delete by title
+        delete_note("my-project", "Meeting Notes: Project Planning")
+
+        # Delete by permalink
+        delete_note("work-docs", "notes/project-planning")
+
+        # Delete with exact path
+        delete_note("research", "experiments/ml-model-results")
+
+        # Common usage pattern
+        if delete_note("my-project", "old-draft"):
+            print("Note deleted successfully")
+        else:
+            print("Note not found or already deleted")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If identifier attempts path traversal
+
+    Warning:
+        This operation is permanent and cannot be undone. The note file
+        will be removed from the filesystem and all references will be lost.
+
+    Note:
+        If the note is not found, this function provides helpful error messages
+        with suggestions for finding the correct identifier, including search
+        commands and alternative formats to try.
+    """
+    async with get_client() as client:
+        active_project = await get_active_project(client, project, context)
+        project_url = active_project.project_url
+
+        try:
+            response = await call_delete(client, f"{project_url}/knowledge/entities/{identifier}")
+            result = DeleteEntitiesResponse.model_validate(response.json())
+
+            if result.deleted:
+                logger.info(
+                    f"Successfully deleted note: {identifier} in project: {active_project.name}"
+                )
+                return True
+            else:
+                logger.warning(f"Delete operation completed but note was not deleted: {identifier}")
+                return False
+
+        except Exception as e:  # pragma: no cover
+            logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")
+            # Return formatted error message for better user experience
+            return _format_delete_error_response(active_project.name, str(e), identifier)