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

basic_memory/mcp/prompts/search.py

@@ -0,0 +1,182 @@
+"""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
+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.base import TimeFrame
+from basic_memory.schemas.search import SearchQuery, SearchResponse
+
+
+@mcp.prompt(
+    name="Search Knowledge Base",
+    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
+    """
+    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.
+            
+            ## Opportunity to Capture Knowledge!
+            
+            This is an excellent opportunity to create new knowledge on this topic. Consider:
+            
+            ```python
+            await write_note(
+                title="{query.capitalize()}",
+                content=f'''
+                # {query.capitalize()}
+                
+                ## Overview
+                [Summary of what we've discussed about {query}]
+                
+                ## Observations
+                - [category] [First observation about {query}]
+                - [category] [Second observation about {query}]
+                
+                ## Relations
+                - relates_to [[Other Relevant Topic]]
+                '''
+            )
+            ```
+            
+            ## Other Suggestions
+            - Try a different search term
+            - Broaden your search criteria
+            - Check recent activity with `recent_activity(timeframe="1w")`
+            """)
+
+    # 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.value}
+            """)
+
+        # Add creation date if available in metadata
+        if 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"  # pragma: no cover
+                )
+            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 result.content:
+            summary += f"- **Excerpt**:\n{result.content}\n"
+
+        # Add permalink for retrieving content
+        if 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}")`
+                """)
+        else:
+            summary += dedent(f"""
+                You can view this file with: `read_file("{result.file_path}")`
+                """)  # pragma: no cover
+
+    # Add next steps with strong write encouragement
+    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()`
+        
+        ## Synthesize and Capture Knowledge
+        
+        Consider creating a new note that synthesizes what you've learned:
+        
+        ```python
+        await write_note(
+            title="Synthesis of {query.capitalize()} Information",
+            content='''
+            # Synthesis of {query.capitalize()} Information
+            
+            ## Overview
+            [Synthesis of the search results and your conversation]
+            
+            ## Key Insights
+            [Summary of main points learned from these results]
+            
+            ## Observations
+            - [insight] [Important observation from search results]
+            - [connection] [How this connects to other topics]
+            
+            ## Relations
+            - relates_to [[{results.results[0].title if results.results else "Related Topic"}]]
+            - extends [[Another Relevant Topic]]
+            '''
+        )
+        ```
+        
+        Remember that capturing synthesized knowledge is one of the most valuable features of Basic Memory.
+        """)
+
+    return summary

basic_memory/mcp/prompts/utils.py

@@ -0,0 +1,155 @@
+"""Utility functions for formatting prompt responses.
+
+These utilities help format data from various tools into consistent,
+user-friendly markdown summaries.
+"""
+
+from dataclasses import dataclass
+from textwrap import dedent
+from typing import List
+
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import (
+    normalize_memory_url,
+    EntitySummary,
+    RelationSummary,
+    ObservationSummary,
+)
+
+
+@dataclass
+class PromptContextItem:
+    primary_results: List[EntitySummary]
+    related_results: List[EntitySummary | RelationSummary | ObservationSummary]
+
+
+@dataclass
+class PromptContext:
+    timeframe: TimeFrame
+    topic: str
+    results: List[PromptContextItem]
+
+
+def format_prompt_context(context: PromptContext) -> str:
+    """Format continuation context into a helpful summary.
+    Returns:
+        Formatted continuation summary
+    """
+    if not context.results:
+        return dedent(f"""
+            # Continuing conversation on: {context.topic}
+
+            This is a memory retrieval session. 
+            The supplied query did not return any information specifically on this topic.
+            
+            ## Opportunity to Capture New Knowledge!
+            
+            This is an excellent chance to start documenting this topic:
+            
+            ```python
+            await write_note(
+                title="{context.topic}",
+                content=f'''
+                # {context.topic}
+                
+                ## Overview
+                [Summary of what we know about {context.topic}]
+                
+                ## Key Points
+                [Main aspects or components of {context.topic}]
+                
+                ## Observations
+                - [category] [First important observation about {context.topic}]
+                - [category] [Second observation about {context.topic}]
+                
+                ## Relations
+                - relates_to [[Related Topic]]
+                - part_of [[Broader Context]]
+                '''
+            )
+            ```
+            
+            ## Other Options
+            
+            Please use the available basic-memory tools to gather relevant context before responding.
+            You can also:
+            - Try a different search term
+            - Check recent activity with `recent_activity(timeframe="1w")`
+            """)
+
+    # Start building our summary with header - add knowledge capture emphasis
+    summary = dedent(f"""
+        # Continuing conversation on: {context.topic}
+
+        This is a memory retrieval session. 
+        
+        Please use the available basic-memory tools to gather relevant context before responding. 
+        Start by executing one of the suggested commands below to retrieve content.
+
+        Here's what I found from previous conversations:
+        
+        > **Knowledge Capture Recommendation:** As you continue this conversation, actively look for opportunities to record new information, decisions, or insights that emerge. Use `write_note()` to document important context.
+        """)
+
+    # Track what we've added to avoid duplicates
+    added_permalinks = set()
+    sections = []
+
+    # Process each context
+    for context in context.results:  # pyright: ignore
+        for primary in context.primary_results:  # pyright: ignore
+            if primary.permalink not in added_permalinks:
+                primary_permalink = primary.permalink
+
+                added_permalinks.add(primary_permalink)
+
+                memory_url = normalize_memory_url(primary_permalink)
+                section = dedent(f"""
+                    --- {memory_url}
+                
+                    ## {primary.title}
+                    - **Type**: {primary.type}
+                    """)
+
+                # Add creation date
+                section += f"- **Created**: {primary.created_at.strftime('%Y-%m-%d %H:%M')}\n"
+
+                # Add content snippet
+                if hasattr(primary, "content") and primary.content:  # pyright: ignore
+                    content = primary.content or ""  # pyright: ignore
+                    if content:
+                        section += f"\n**Excerpt**:\n{content}\n"
+
+                section += dedent(f"""
+    
+                    You can read this document with: `read_note("{primary_permalink}")`
+                    """)
+                sections.append(section)
+
+        if context.related_results:  # pyright: ignore
+            section += dedent(  # pyright: ignore
+                """   
+                ## Related Context
+                """
+            )
+
+            for related in context.related_results:  # pyright: ignore
+                section_content = dedent(f"""
+                    - type: **{related.type}**
+                    - title: {related.title}
+                    """)
+                if related.permalink:
+                    section_content += (
+                        f'You can view this document with: `read_note("{related.permalink}")`'
+                    )
+                else:
+                    section_content += (
+                        f'You can view this file with: `read_file("{related.file_path}")`'
+                    )
+
+                section += section_content
+                sections.append(section)
+
+    # Add all sections
+    summary += "\n".join(sections)
+    return 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")

basic_memory/mcp/tools/__init__.py

@@ -6,31 +6,22 @@ all tools with the MCP server.
 """
 
 # Import tools to register them with MCP
-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.delete_note import delete_note
+from basic_memory.mcp.tools.read_content import read_content
+from basic_memory.mcp.tools.build_context import build_context
+from basic_memory.mcp.tools.recent_activity import recent_activity
+from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.mcp.tools.write_note import write_note
 from basic_memory.mcp.tools.search import search
-
-from basic_memory.mcp.tools.knowledge import (
-    delete_entities,
-    get_entity,
-    get_entities,
-)
+from basic_memory.mcp.tools.canvas import canvas
 
 __all__ = [
-    # Knowledge graph tools
-    "delete_entities",
-    "get_entity",
-    "get_entities",
-    # Search tools
-    "search",
-    # memory tools
     "build_context",
-    "recent_activity",
-    # notes
+    "canvas",
+    "delete_note",
+    "read_content",
     "read_note",
+    "recent_activity",
+    "search",
     "write_note",
-    # file edit
-    # "ai_edit",
 ]

basic_memory/mcp/tools/build_context.py

@@ -0,0 +1,85 @@
+"""Build context tool for Basic Memory MCP server."""
+
+from typing import Optional
+
+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,
+    MemoryUrl,
+    memory_url_path,
+    normalize_memory_url,
+)
+
+
+@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.
+    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,
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
+) -> GraphContext:
+    """Get context needed to continue a discussion.
+
+    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.
+
+    Args:
+        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)
+
+    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("memory://specs/search")
+
+        # Get deeper context about a component
+        build_context("memory://components/memory-service", depth=2)
+
+        # Look at recent changes to a specification
+        build_context("memory://specs/document-format", timeframe="today")
+
+        # 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,
+            "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,97 @@
+"""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
+
+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"
+        }
+      ]
+    }
+    ```
+    """
+    # 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/delete_note.py

@@ -0,0 +1,28 @@
+from basic_memory.mcp.tools.utils import call_delete
+
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.async_client import client
+from basic_memory.schemas import DeleteEntitiesResponse
+
+
+@mcp.tool(description="Delete a note by title or permalink")
+async def delete_note(identifier: str) -> bool:
+    """Delete a note from the knowledge base.
+
+    Args:
+        identifier: Note title or permalink
+
+    Returns:
+        True if note was deleted, False otherwise
+
+    Examples:
+        # Delete by title
+        delete_note("Meeting Notes: Project Planning")
+
+        # Delete by permalink
+        delete_note("notes/project-planning")
+    """
+    response = await call_delete(client, f"/knowledge/entities/{identifier}")
+    result = DeleteEntitiesResponse.model_validate(response.json())
+    return result.deleted

basic_memory/mcp/tools/project_info.py

@@ -0,0 +1,51 @@
+"""Project info tool for Basic Memory MCP server."""
+
+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 import ProjectInfoResponse
+
+
+@mcp.tool(
+    description="Get information and statistics about the current Basic Memory project.",
+)
+async def project_info() -> ProjectInfoResponse:
+    """Get comprehensive information about the current Basic Memory project.
+
+    This tool provides detailed statistics and status information about your
+    Basic Memory project, including:
+
+    - Project configuration
+    - Entity, observation, and relation counts
+    - Graph metrics (most connected entities, isolated entities)
+    - Recent activity and growth over time
+    - System status (database, watch service, version)
+
+    Use this tool to:
+    - Verify your Basic Memory installation is working correctly
+    - Get insights into your knowledge base structure
+    - Monitor growth and activity over time
+    - Identify potential issues like unresolved relations
+
+    Returns:
+        Detailed project information and statistics
+
+    Examples:
+        # Get information about the current project
+        info = await project_info()
+
+        # Check entity counts
+        print(f"Total entities: {info.statistics.total_entities}")
+
+        # Check system status
+        print(f"Basic Memory version: {info.system.version}")
+    """
+    logger.info("Getting project info")
+
+    # Call the API endpoint
+    response = await call_get(client, "/stats/project-info")
+
+    # Convert response to ProjectInfoResponse
+    return ProjectInfoResponse.model_validate(response.json())