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

basic_memory/mcp/prompts/search.py

@@ -0,0 +1,127 @@
+"""Search prompts for Basic Memory MCP server.
+
+These prompts help users search and explore their knowledge base.
+"""
+
+from textwrap import dedent
+from typing import Annotated, Optional
+
+from loguru import logger
+import logfire
+from pydantic import Field
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.search import search as search_tool
+from basic_memory.schemas.search import SearchQuery, SearchResponse
+from basic_memory.schemas.base import TimeFrame
+
+
+@mcp.prompt(
+    name="search",
+    description="Search across all content in basic-memory",
+)
+async def search_prompt(
+    query: str,
+    timeframe: Annotated[
+        Optional[TimeFrame],
+        Field(description="How far back to search (e.g. '1d', '1 week')"),
+    ] = None,
+) -> str:
+    """Search across all content in basic-memory.
+
+    This prompt helps search for content in the knowledge base and
+    provides helpful context about the results.
+
+    Args:
+        query: The search text to look for
+        timeframe: Optional timeframe to limit results (e.g. '1d', '1 week')
+
+    Returns:
+        Formatted search results with context
+    """
+    with logfire.span("Searching knowledge base", query=query, timeframe=timeframe):  # pyright: ignore
+        logger.info(f"Searching knowledge base, query: {query}, timeframe: {timeframe}")
+
+        search_results = await search_tool(SearchQuery(text=query, after_date=timeframe))
+        return format_search_results(query, search_results, timeframe)
+
+
+def format_search_results(
+    query: str, results: SearchResponse, timeframe: Optional[TimeFrame] = None
+) -> str:
+    """Format search results into a helpful summary.
+
+    Args:
+        query: The search query
+        results: Search results object
+        timeframe: How far back results were searched
+
+    Returns:
+        Formatted search results summary
+    """
+    if not results.results:
+        return dedent(f"""
+            # Search Results for: "{query}"
+            
+            I couldn't find any results for this query.
+            
+            ## Suggestions
+            - Try a different search term
+            - Broaden your search criteria
+            - Check recent activity with `recent_activity(timeframe="1w")`
+            - Create new content with `write_note(...)`
+            """)
+
+    # Start building our summary with header
+    time_info = f" (after {timeframe})" if timeframe else ""
+    summary = dedent(f"""
+        # Search Results for: "{query}"{time_info}
+        
+        This is a memory search session.
+        Please use the available basic-memory tools to gather relevant context before responding.
+        I found {len(results.results)} results that match your query.
+        
+        Here are the most relevant results:
+        """)
+
+    # Add each search result
+    for i, result in enumerate(results.results[:5]):  # Limit to top 5 results
+        summary += dedent(f"""
+            ## {i + 1}. {result.title}
+            - **Type**: {result.type}
+            """)
+
+        # Add creation date if available in metadata
+        if hasattr(result, "metadata") and result.metadata and "created_at" in result.metadata:
+            created_at = result.metadata["created_at"]
+            if hasattr(created_at, "strftime"):
+                summary += f"- **Created**: {created_at.strftime('%Y-%m-%d %H:%M')}\n"
+            elif isinstance(created_at, str):
+                summary += f"- **Created**: {created_at}\n"
+
+        # Add score and excerpt
+        summary += f"- **Relevance Score**: {result.score:.2f}\n"
+        # Add excerpt if available in metadata
+        if hasattr(result, "metadata") and result.metadata and "excerpt" in result.metadata:
+            summary += f"- **Excerpt**: {result.metadata['excerpt']}\n"
+
+        # Add permalink for retrieving content
+        if hasattr(result, "permalink") and result.permalink:
+            summary += dedent(f"""
+                
+                You can view this content with: `read_note("{result.permalink}")`
+                Or explore its context with: `build_context("memory://{result.permalink}")`
+                """)
+
+    # Add next steps
+    summary += dedent(f"""
+        ## Next Steps
+        
+        You can:
+        - Refine your search: `search("{query} AND additional_term")`
+        - Exclude terms: `search("{query} NOT exclude_term")`
+        - View more results: `search("{query}", after_date=None)`
+        - Check recent activity: `recent_activity()`
+        """)
+
+    return summary

basic_memory/mcp/prompts/utils.py

@@ -0,0 +1,98 @@
+"""Utility functions for formatting prompt responses.
+
+These utilities help format data from various tools into consistent,
+user-friendly markdown summaries.
+"""
+
+from basic_memory.schemas.memory import GraphContext
+
+
+def format_context_summary(header: str, context: GraphContext) -> str:
+    """Format GraphContext as a helpful markdown summary.
+
+    This creates a user-friendly markdown response that explains the context
+    and provides guidance on how to explore further.
+
+    Args:
+        header: The title to use for the summary
+        context: The GraphContext object to format
+
+    Returns:
+        Formatted markdown string with the context summary
+    """
+    summary = []
+
+    # Extract URI for reference
+    uri = context.metadata.uri or "a/permalink-value"
+
+    # Add header
+    summary.append(f"{header}")
+    summary.append("")
+
+    # Primary document section
+    if context.primary_results:
+        summary.append(f"## Primary Documents ({len(context.primary_results)})")
+
+        for primary in context.primary_results:
+            summary.append(f"### {primary.title}")
+            summary.append(f"- **Type**: {primary.type}")
+            summary.append(f"- **Path**: {primary.file_path}")
+            summary.append(f"- **Created**: {primary.created_at.strftime('%Y-%m-%d %H:%M')}")
+            summary.append("")
+            summary.append(
+                f'To view this document\'s content: `read_note("{primary.permalink}")` or `read_note("{primary.title}")` '
+            )
+            summary.append("")
+    else:
+        summary.append("\nNo primary documents found.")
+
+    # Related documents section
+    if context.related_results:
+        summary.append(f"## Related Documents ({len(context.related_results)})")
+
+        # Group by relation type for better organization
+        relation_types = {}
+        for rel in context.related_results:
+            if hasattr(rel, "relation_type"):
+                rel_type = rel.relation_type  # pyright: ignore
+                if rel_type not in relation_types:
+                    relation_types[rel_type] = []
+                relation_types[rel_type].append(rel)
+
+        # Display relations grouped by type
+        for rel_type, relations in relation_types.items():
+            summary.append(f"### {rel_type.replace('_', ' ').title()} ({len(relations)})")
+
+            for rel in relations:
+                if hasattr(rel, "to_id") and rel.to_id:
+                    summary.append(f"- **{rel.to_id}**")
+                    summary.append(f'  - View document: `read_note("{rel.to_id}")` ')
+                    summary.append(
+                        f'  - Explore connections: `build_context("memory://{rel.to_id}")` '
+                    )
+                else:
+                    summary.append(f"- **Unresolved relation**: {rel.permalink}")
+            summary.append("")
+
+    # Next steps section
+    summary.append("## Next Steps")
+    summary.append("Here are some ways to explore further:")
+
+    search_term = uri.split("/")[-1]
+    summary.append(f'- **Search related topics**: `search({{"text": "{search_term}"}})`')
+
+    summary.append('- **Check recent changes**: `recent_activity(timeframe="3 days")`')
+    summary.append(f'- **Explore all relations**: `build_context("memory://{uri}/*")`')
+
+    # Tips section
+    summary.append("")
+    summary.append("## Tips")
+    summary.append(
+        f'- For more specific context, increase depth: `build_context("memory://{uri}", depth=2)`'
+    )
+    summary.append(
+        "- You can follow specific relation types using patterns like: `memory://document/relation-type/*`"
+    )
+    summary.append("- Look for connected documents by checking relations between them")
+
+    return "\n".join(summary)

basic_memory/mcp/server.py

@@ -1,15 +1,11 @@
 """Enhanced FastMCP server instance for Basic Memory."""
 
 from mcp.server.fastmcp import FastMCP
-
-from basic_memory.utils import setup_logging
+from mcp.server.fastmcp.utilities.logging import configure_logging
 
 # mcp console logging
-# configure_logging(level='INFO')
-
+configure_logging(level="INFO")
 
-# start our out file logging
-setup_logging(log_file=".basic-memory/basic-memory.log")
 
 # Create the shared server instance
-mcp = FastMCP("Basic Memory")
+mcp = FastMCP("Basic Memory")

basic_memory/mcp/tools/__init__.py

@@ -6,11 +6,11 @@ all tools with the MCP server.
 """
 
 # Import tools to register them with MCP
+from basic_memory.mcp.tools.resource import read_resource
 from basic_memory.mcp.tools.memory import build_context, recent_activity
-
-# from basic_memory.mcp.tools.ai_edit import ai_edit
 from basic_memory.mcp.tools.notes import read_note, write_note
 from basic_memory.mcp.tools.search import search
+from basic_memory.mcp.tools.canvas import canvas
 
 from basic_memory.mcp.tools.knowledge import (
     delete_entities,
@@ -31,6 +31,8 @@ __all__ = [
     # notes
     "read_note",
     "write_note",
-    # file edit
-    # "ai_edit",
+    # files
+    "read_resource",
+    # canvas
+    "canvas",
 ]

basic_memory/mcp/tools/canvas.py

@@ -0,0 +1,99 @@
+"""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
+
+import logfire
+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_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,
+) -> 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.
+
+    For the full JSON Canvas 1.0 specification, see the 'spec://canvas' resource.
+
+    Args:
+        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: The folder where the file should be saved
+
+    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"
+        }
+      ]
+    }
+    ```
+    """
+    with logfire.span("Creating canvas", folder=folder, title=title):  # type: ignore
+        # 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}")
+        response = await call_put(client, f"/resource/{file_path}", json=canvas_json)
+
+        # 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/knowledge.py

@@ -1,8 +1,10 @@
 """Knowledge graph management tools for Basic Memory MCP server."""
 
+import logfire
+
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get, call_post
-from basic_memory.schemas.base import Permalink
+from basic_memory.schemas.memory import memory_url_path
 from basic_memory.schemas.request import (
     GetEntitiesRequest,
 )
@@ -16,15 +18,17 @@ from basic_memory.mcp.async_client import client
 @mcp.tool(
     description="Get complete information about a specific entity including observations and relations",
 )
-async def get_entity(permalink: Permalink) -> EntityResponse:
+async def get_entity(identifier: str) -> EntityResponse:
     """Get a specific entity info by its permalink.
 
     Args:
-        permalink: Path identifier for the entity
+        identifier: Path identifier for the entity
     """
-    url = f"/knowledge/entities/{permalink}"
-    response = await call_get(client, url)
-    return EntityResponse.model_validate(response.json())
+    with logfire.span("Getting entity", permalink=identifier):  # pyright: ignore [reportGeneralTypeIssues]
+        permalink = memory_url_path(identifier)
+        url = f"/knowledge/entities/{permalink}"
+        response = await call_get(client, url)
+        return EntityResponse.model_validate(response.json())
 
 
 @mcp.tool(
@@ -39,11 +43,16 @@ async def get_entities(request: GetEntitiesRequest) -> EntityListResponse:
     Returns:
         EntityListResponse containing complete details for each requested entity
     """
-    url = "/knowledge/entities"
-    response = await call_get(
-        client, url, params=[("permalink", permalink) for permalink in request.permalinks]
-    )
-    return EntityListResponse.model_validate(response.json())
+    with logfire.span("Getting multiple entities", permalink_count=len(request.permalinks)):  # pyright: ignore [reportGeneralTypeIssues]
+        url = "/knowledge/entities"
+        response = await call_get(
+            client,
+            url,
+            params=[
+                ("permalink", memory_url_path(identifier)) for identifier in request.permalinks
+            ],
+        )
+        return EntityListResponse.model_validate(response.json())
 
 
 @mcp.tool(
@@ -51,6 +60,9 @@ async def get_entities(request: GetEntitiesRequest) -> EntityListResponse:
 )
 async def delete_entities(request: DeleteEntitiesRequest) -> DeleteEntitiesResponse:
     """Delete entities from the knowledge graph."""
-    url = "/knowledge/entities/delete"
-    response = await call_post(client, url, json=request.model_dump())
-    return DeleteEntitiesResponse.model_validate(response.json())
+    with logfire.span("Deleting entities", permalink_count=len(request.permalinks)):  # pyright: ignore [reportGeneralTypeIssues]
+        url = "/knowledge/entities/delete"
+
+        request.permalinks = [memory_url_path(permlink) for permlink in request.permalinks]
+        response = await call_post(client, url, json=request.model_dump())
+        return DeleteEntitiesResponse.model_validate(response.json())

basic_memory/mcp/tools/memory.py

@@ -1,8 +1,9 @@
 """Discussion context tools for Basic Memory MCP server."""
 
-from typing import Optional, Literal, List
+from typing import Optional, List
 
 from loguru import logger
+import logfire
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
@@ -14,6 +15,7 @@ from basic_memory.schemas.memory import (
     normalize_memory_url,
 )
 from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.tool(
@@ -32,7 +34,9 @@ async def build_context(
     url: MemoryUrl,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
-    max_results: int = 10,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
 ) -> GraphContext:
     """Get context needed to continue a discussion.
 
@@ -44,7 +48,9 @@ async def build_context(
         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"
-        max_results: Maximum number of results to return (default: 10)
+        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:
@@ -65,14 +71,21 @@ async def build_context(
         # Research the history of a feature
         build_context("memory://features/knowledge-graph", timeframe="3 months ago")
     """
-    logger.info(f"Building context from {url}")
-    url = normalize_memory_url(url)
-    response = await call_get(
-        client,
-        f"/memory/{memory_url_path(url)}",
-        params={"depth": depth, "timeframe": timeframe, "max_results": max_results},
-    )
-    return GraphContext.model_validate(response.json())
+    with logfire.span("Building context", url=url, depth=depth, timeframe=timeframe):  # pyright: ignore [reportGeneralTypeIssues]
+        logger.info(f"Building context from {url}")
+        url = normalize_memory_url(url)
+        response = await call_get(
+            client,
+            f"/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())
 
 
 @mcp.tool(
@@ -88,10 +101,12 @@ async def build_context(
     """,
 )
 async def recent_activity(
-    type: List[Literal["entity", "observation", "relation"]] = [],
+    type: Optional[List[SearchItemType]] = None,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
-    max_results: int = 10,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
 ) -> GraphContext:
     """Get recent activity across the knowledge base.
 
@@ -106,7 +121,9 @@ async def recent_activity(
             - Relative: "2 days ago", "last week", "yesterday"
             - Points in time: "2024-01-01", "January 1st"
             - Standard format: "7d", "24h"
-        max_results: Maximum number of results to return (default: 10)
+        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:
@@ -132,20 +149,29 @@ async def recent_activity(
         - 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}, depth={depth}, timeframe={timeframe}, max_results={max_results}"
-    )
-    params = {
-        "depth": depth,
-        "timeframe": timeframe,
-        "max_results": max_results,
-    }
-    if type:
-        params["type"] = type
-
-    response = await call_get(
-        client,
-        "/memory/recent",
-        params=params,
-    )
-    return GraphContext.model_validate(response.json())
+    with logfire.span("Getting recent activity", type=type, depth=depth, timeframe=timeframe):  # pyright: ignore [reportGeneralTypeIssues]
+        logger.info(
+            f"Getting recent activity from {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())