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

basic_memory/mcp/tools/read_content.py

@@ -0,0 +1,229 @@
+"""File reading tool for Basic Memory MCP server.
+
+This module provides tools for reading raw file content directly,
+supporting various file types including text, images, and other binary files.
+Files are read directly without any knowledge graph processing.
+"""
+
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.tools.utils import call_get
+from basic_memory.schemas.memory import memory_url_path
+
+import base64
+import io
+from PIL import Image as PILImage
+
+
+def calculate_target_params(content_length):
+    """Calculate initial quality and size based on input file size"""
+    target_size = 350000  # Reduced target for more safety margin
+    ratio = content_length / target_size
+
+    logger.debug(
+        "Calculating target parameters",
+        content_length=content_length,
+        ratio=ratio,
+        target_size=target_size,
+    )
+
+    if ratio > 4:
+        # Very large images - start very aggressive
+        return 50, 600  # Lower initial quality and size
+    elif ratio > 2:
+        return 60, 800
+    else:
+        return 70, 1000
+
+
+def resize_image(img, max_size):
+    """Resize image maintaining aspect ratio"""
+    original_dimensions = {"width": img.width, "height": img.height}
+
+    if img.width > max_size or img.height > max_size:
+        ratio = min(max_size / img.width, max_size / img.height)
+        new_size = (int(img.width * ratio), int(img.height * ratio))
+        logger.debug("Resizing image", original=original_dimensions, target=new_size, ratio=ratio)
+        return img.resize(new_size, PILImage.Resampling.LANCZOS)
+
+    logger.debug("No resize needed", dimensions=original_dimensions)
+    return img
+
+
+def optimize_image(img, content_length, max_output_bytes=350000):
+    """Iteratively optimize image with aggressive size reduction"""
+    stats = {
+        "dimensions": {"width": img.width, "height": img.height},
+        "mode": img.mode,
+        "estimated_memory": (img.width * img.height * len(img.getbands())),
+    }
+
+    initial_quality, initial_size = calculate_target_params(content_length)
+
+    logger.debug(
+        "Starting optimization",
+        image_stats=stats,
+        content_length=content_length,
+        initial_quality=initial_quality,
+        initial_size=initial_size,
+        max_output_bytes=max_output_bytes,
+    )
+
+    quality = initial_quality
+    size = initial_size
+
+    # Convert to RGB if needed
+    if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):
+        img = img.convert("RGB")
+        logger.debug("Converted to RGB mode")
+
+    iteration = 0
+    min_size = 300  # Absolute minimum size
+    min_quality = 20  # Absolute minimum quality
+
+    while True:
+        iteration += 1
+        buf = io.BytesIO()
+        resized = resize_image(img, size)
+
+        resized.save(
+            buf,
+            format="JPEG",
+            quality=quality,
+            optimize=True,
+            progressive=True,
+            subsampling="4:2:0",
+        )
+
+        output_size = buf.getbuffer().nbytes
+        reduction_ratio = output_size / content_length
+
+        logger.debug(
+            "Optimization attempt",
+            iteration=iteration,
+            quality=quality,
+            size=size,
+            output_bytes=output_size,
+            target_bytes=max_output_bytes,
+            reduction_ratio=f"{reduction_ratio:.2f}",
+        )
+
+        if output_size < max_output_bytes:
+            logger.info(
+                "Image optimization complete",
+                final_size=output_size,
+                quality=quality,
+                dimensions={"width": resized.width, "height": resized.height},
+                reduction_ratio=f"{reduction_ratio:.2f}",
+            )
+            return buf.getvalue()
+
+        # Very aggressive reduction for large files
+        if content_length > 2000000:  # 2MB+   # pragma: no cover
+            quality = max(min_quality, quality - 20)
+            size = max(min_size, int(size * 0.6))
+        elif content_length > 1000000:  # 1MB+ # pragma: no cover
+            quality = max(min_quality, quality - 15)
+            size = max(min_size, int(size * 0.7))
+        else:
+            quality = max(min_quality, quality - 10)  # pragma: no cover
+            size = max(min_size, int(size * 0.8))  # pragma: no cover
+
+        logger.debug("Reducing parameters", new_quality=quality, new_size=size)  # pragma: no cover
+
+        # If we've hit minimum values and still too big
+        if quality <= min_quality and size <= min_size:  # pragma: no cover
+            logger.warning(
+                "Reached minimum parameters",
+                final_size=output_size,
+                over_limit_by=output_size - max_output_bytes,
+            )
+            return buf.getvalue()
+
+
+@mcp.tool(description="Read a file's raw content by path or permalink")
+async def read_content(path: str) -> dict:
+    """Read a file's raw content by path or permalink.
+
+    This tool provides direct access to file content in the knowledge base,
+    handling different file types appropriately:
+    - Text files (markdown, code, etc.) are returned as plain text
+    - Images are automatically resized/optimized for display
+    - Other binary files are returned as base64 if below size limits
+
+    Args:
+        path: The path or permalink to the file. Can be:
+            - A regular file path (docs/example.md)
+            - A memory URL (memory://docs/example)
+            - A permalink (docs/example)
+
+    Returns:
+        A dictionary with the file content and metadata:
+        - For text: {"type": "text", "text": "content", "content_type": "text/markdown", "encoding": "utf-8"}
+        - For images: {"type": "image", "source": {"type": "base64", "media_type": "image/jpeg", "data": "base64_data"}}
+        - For other files: {"type": "document", "source": {"type": "base64", "media_type": "content_type", "data": "base64_data"}}
+        - For errors: {"type": "error", "error": "error message"}
+
+    Examples:
+        # Read a markdown file
+        result = await read_file("docs/project-specs.md")
+
+        # Read an image
+        image_data = await read_file("assets/diagram.png")
+
+        # Read using memory URL
+        content = await read_file("memory://docs/architecture")
+    """
+    logger.info("Reading file", path=path)
+
+    url = memory_url_path(path)
+    response = await call_get(client, f"/resource/{url}")
+    content_type = response.headers.get("content-type", "application/octet-stream")
+    content_length = int(response.headers.get("content-length", 0))
+
+    logger.debug("Resource metadata", content_type=content_type, size=content_length, path=path)
+
+    # Handle text or json
+    if content_type.startswith("text/") or content_type == "application/json":
+        logger.debug("Processing text resource")
+        return {
+            "type": "text",
+            "text": response.text,
+            "content_type": content_type,
+            "encoding": "utf-8",
+        }
+
+    # Handle images
+    elif content_type.startswith("image/"):
+        logger.debug("Processing image")
+        img = PILImage.open(io.BytesIO(response.content))
+        img_bytes = optimize_image(img, content_length)
+
+        return {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": "image/jpeg",
+                "data": base64.b64encode(img_bytes).decode("utf-8"),
+            },
+        }
+
+    # Handle other file types
+    else:
+        logger.debug(f"Processing binary resource content_type {content_type}")
+        if content_length > 350000:  # pragma: no cover
+            logger.warning("Document too large for response", size=content_length)
+            return {
+                "type": "error",
+                "error": f"Document size {content_length} bytes exceeds maximum allowed size",
+            }
+        return {
+            "type": "document",
+            "source": {
+                "type": "base64",
+                "media_type": content_type,
+                "data": base64.b64encode(response.content).decode("utf-8"),
+            },
+        }

basic_memory/mcp/tools/read_note.py

@@ -0,0 +1,190 @@
+"""Read note tool for Basic Memory MCP server."""
+
+from textwrap import dedent
+
+from loguru import logger
+
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.search import search
+from basic_memory.mcp.tools.utils import call_get
+from basic_memory.schemas.memory import memory_url_path
+from basic_memory.schemas.search import SearchQuery
+
+
+@mcp.tool(
+    description="Read a markdown note by title or permalink.",
+)
+async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
+    """Read a markdown note from the knowledge base.
+
+    This tool finds and retrieves a note by its title, permalink, or content search,
+    returning the raw markdown content including observations, relations, and metadata.
+    It will try multiple lookup strategies to find the most relevant note.
+
+    Args:
+        identifier: The title or permalink of the note to read
+                   Can be a full memory:// URL, a permalink, a title, or search text
+        page: Page number for paginated results (default: 1)
+        page_size: Number of items per page (default: 10)
+
+    Returns:
+        The full markdown content of the note if found, or helpful guidance if not found.
+
+    Examples:
+        # Read by permalink
+        read_note("specs/search-spec")
+
+        # Read by title
+        read_note("Search Specification")
+
+        # Read with memory URL
+        read_note("memory://specs/search-spec")
+
+        # Read with pagination
+        read_note("Project Updates", page=2, page_size=5)
+    """
+    # Get the file via REST API - first try direct permalink lookup
+    entity_path = memory_url_path(identifier)
+    path = f"/resource/{entity_path}"
+    logger.info(f"Attempting to read note from URL: {path}")
+
+    try:
+        # Try direct lookup first
+        response = await call_get(client, path, params={"page": page, "page_size": page_size})
+
+        # If successful, return the content
+        if response.status_code == 200:
+            logger.info("Returning read_note result from resource: {path}", path=entity_path)
+            return response.text
+    except Exception as e:  # pragma: no cover
+        logger.info(f"Direct lookup failed for '{path}': {e}")
+        # Continue to fallback methods
+
+    # Fallback 1: Try title search via API
+    logger.info(f"Search title for: {identifier}")
+    title_results = await search(SearchQuery(title=identifier))
+
+    if title_results and title_results.results:
+        result = title_results.results[0]  # Get the first/best match
+        if result.permalink:
+            try:
+                # Try to fetch the content using the found permalink
+                path = f"/resource/{result.permalink}"
+                response = await call_get(
+                    client, path, params={"page": page, "page_size": page_size}
+                )
+
+                if response.status_code == 200:
+                    logger.info(f"Found note by title search: {result.permalink}")
+                    return response.text
+            except Exception as e:  # pragma: no cover
+                logger.info(
+                    f"Failed to fetch content for found title match {result.permalink}: {e}"
+                )
+    else:
+        logger.info(f"No results in title search for: {identifier}")
+
+    # Fallback 2: Text search as a last resort
+    logger.info(f"Title search failed, trying text search for: {identifier}")
+    text_results = await search(SearchQuery(text=identifier))
+
+    # We didn't find a direct match, construct a helpful error message
+    if not text_results or not text_results.results:
+        # No results at all
+        return format_not_found_message(identifier)
+    else:
+        # We found some related results
+        return format_related_results(identifier, text_results.results[:5])
+
+
+def format_not_found_message(identifier: str) -> str:
+    """Format a helpful message when no note was found."""
+    return dedent(f"""
+        # Note Not Found: "{identifier}"
+        
+        I couldn't find any notes matching "{identifier}". Here are some suggestions:
+        
+        ## Check Identifier Type
+        - If you provided a title, try using the exact permalink instead
+        - If you provided a permalink, check for typos or try a broader search
+        
+        ## Search Instead
+        Try searching for related content:
+        ```
+        search(query="{identifier}")
+        ```
+        
+        ## Recent Activity
+        Check recently modified notes:
+        ```
+        recent_activity(timeframe="7d")
+        ```
+        
+        ## Create New Note
+        This might be a good opportunity to create a new note on this topic:
+        ```
+        write_note(
+            title="{identifier.capitalize()}",
+            content='''
+            # {identifier.capitalize()}
+            
+            ## Overview
+            [Your content here]
+            
+            ## Observations
+            - [category] [Observation about {identifier}]
+            
+            ## Relations
+            - relates_to [[Related Topic]]
+            ''',
+            folder="notes"
+        )
+        ```
+    """)
+
+
+def format_related_results(identifier: str, results) -> str:
+    """Format a helpful message with related results when an exact match wasn't found."""
+    message = dedent(f"""
+        # Note Not Found: "{identifier}"
+        
+        I couldn't find an exact match for "{identifier}", but I found some related notes:
+        
+        """)
+
+    for i, result in enumerate(results):
+        message += dedent(f"""
+            ## {i + 1}. {result.title}
+            - **Type**: {result.type.value}
+            - **Permalink**: {result.permalink}
+            
+            You can read this note with:
+            ```
+            read_note("{result.permalink}")
+            ```
+            
+            """)
+
+    message += dedent("""
+        ## Try More Specific Lookup
+        For exact matches, try using the full permalink from one of the results above.
+        
+        ## Search For More Results
+        To see more related content:
+        ```
+        search(query="{identifier}")
+        ```
+        
+        ## Create New Note
+        If none of these match what you're looking for, consider creating a new note:
+        ```
+        write_note(
+            title="[Your title]",
+            content="[Your content]",
+            folder="notes"
+        )
+        ```
+    """)
+
+    return message

basic_memory/mcp/tools/recent_activity.py

@@ -0,0 +1,100 @@
+"""Recent activity tool for Basic Memory MCP server."""
+
+from typing import Optional, List
+
+from loguru import logger
+
+from basic_memory.mcp.async_client import client
+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
+from basic_memory.schemas.search import SearchItemType
+
+
+@mcp.tool(
+    description="""Get recent activity from across the knowledge base.
+    
+    Timeframe supports natural language formats like:
+    - "2 days ago"  
+    - "last week"
+    - "yesterday" 
+    - "today"
+    - "3 weeks ago"
+    Or standard formats like "7d"
+    """,
+)
+async def recent_activity(
+    type: Optional[List[SearchItemType]] = None,
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+) -> GraphContext:
+    """Get recent activity across the knowledge base.
+
+    Args:
+        type: Filter by content type(s). Valid options:
+            - ["entity"] for knowledge entities
+            - ["relation"] for connections between entities
+            - ["observation"] for notes and observations
+            Multiple types can be combined: ["entity", "relation"]
+        depth: How many relation hops to traverse (1-3 recommended)
+        timeframe: Time window to search. Supports natural language:
+            - Relative: "2 days ago", "last week", "yesterday"
+            - Points in time: "2024-01-01", "January 1st"
+            - Standard format: "7d", "24h"
+        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)
+
+    Returns:
+        GraphContext containing:
+            - primary_results: Latest activities matching the filters
+            - related_results: Connected content via relations
+            - metadata: Query details and statistics
+
+    Examples:
+        # Get all entities for the last 10 days (default)
+        recent_activity()
+
+        # Get all entities from yesterday
+        recent_activity(type=["entity"], timeframe="yesterday")
+
+        # Get recent relations and observations
+        recent_activity(type=["relation", "observation"], timeframe="today")
+
+        # Look back further with more context
+        recent_activity(type=["entity"], depth=2, timeframe="2 weeks ago")
+
+    Notes:
+        - Higher depth values (>3) may impact performance with large result sets
+        - For focused queries, consider using build_context with a specific URI
+        - Max timeframe is 1 year in the past
+    """
+    logger.info(
+        f"Getting recent activity from type={type}, depth={depth}, timeframe={timeframe}, page={page}, page_size={page_size}, max_related={max_related}"
+    )
+    params = {
+        "page": page,
+        "page_size": page_size,
+        "max_related": max_related,
+    }
+    if depth:
+        params["depth"] = depth
+    if timeframe:
+        params["timeframe"] = timeframe  # pyright: ignore
+
+    # send enum values if we have an enum, else send string value
+    if type:
+        params["type"] = [  # pyright: ignore
+            type.value if isinstance(type, SearchItemType) else type for type in type
+        ]
+
+    response = await call_get(
+        client,
+        "/memory/recent",
+        params=params,
+    )
+    return GraphContext.model_validate(response.json())

basic_memory/mcp/tools/search.py

@@ -1,6 +1,5 @@
 """Search tools for Basic Memory MCP server."""
 
-import logfire
 from loguru import logger
 
 from basic_memory.mcp.server import mcp
@@ -15,24 +14,64 @@ from basic_memory.mcp.async_client import client
 async def search(query: SearchQuery, page: int = 1, page_size: int = 10) -> SearchResponse:
     """Search across all content in basic-memory.
 
+    This tool searches the knowledge base using full-text search, pattern matching,
+    or exact permalink lookup. It supports filtering by content type, entity type,
+    and date.
+
     Args:
         query: SearchQuery object with search parameters including:
-            - text: Search text (required)
-            - types: Optional list of content types to search ("document" or "entity")
-            - entity_types: Optional list of entity types to filter by
-            - after_date: Optional date filter for recent content
-        page: the page number of results to return (default 1)
-        page_size: the number of results to return per page (default 10)
+            - text: Full-text search (e.g., "project planning")
+              Supports boolean operators: AND, OR, NOT and parentheses for grouping
+            - title: Search only in titles (e.g., "Meeting notes")
+            - permalink: Exact permalink match (e.g., "docs/meeting-notes")
+            - permalink_match: Pattern matching for permalinks (e.g., "docs/*-notes")
+            - types: Optional list of content types to search (e.g., ["entity", "observation"])
+            - entity_types: Optional list of entity types to filter by (e.g., ["note", "person"])
+            - after_date: Optional date filter for recent content (e.g., "1 week", "2d")
+        page: The page number of results to return (default 1)
+        page_size: The number of results to return per page (default 10)
 
     Returns:
-        SearchResponse with search results and metadata
+        SearchResponse with results and pagination info
+
+    Examples:
+        # Basic text search
+        results = await search(SearchQuery(text="project planning"))
+
+        # Boolean AND search (both terms must be present)
+        results = await search(SearchQuery(text="project AND planning"))
+
+        # Boolean OR search (either term can be present)
+        results = await search(SearchQuery(text="project OR meeting"))
+
+        # Boolean NOT search (exclude terms)
+        results = await search(SearchQuery(text="project NOT meeting"))
+
+        # Boolean search with grouping
+        results = await search(SearchQuery(text="(project OR planning) AND notes"))
+
+        # Search with type filter
+        results = await search(SearchQuery(
+            text="meeting notes",
+            types=["entity"],
+        ))
+
+        # Search for recent content
+        results = await search(SearchQuery(
+            text="bug report",
+            after_date="1 week"
+        ))
+
+        # Pattern matching on permalinks
+        results = await search(SearchQuery(
+            permalink_match="docs/meeting-*"
+        ))
     """
-    with logfire.span("Searching for {query}", query=query):  # pyright: ignore [reportGeneralTypeIssues]
-        logger.info(f"Searching for {query}")
-        response = await call_post(
-            client,
-            "/search/",
-            json=query.model_dump(),
-            params={"page": page, "page_size": page_size},
-        )
-        return SearchResponse.model_validate(response.json())
+    logger.info(f"Searching for {query}")
+    response = await call_post(
+        client,
+        "/search/",
+        json=query.model_dump(),
+        params={"page": page, "page_size": page_size},
+    )
+    return SearchResponse.model_validate(response.json())