basic-memory 0.8.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

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())