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

basic_memory/mcp/prompts/utils.py

@@ -4,95 +4,152 @@ These utilities help format data from various tools into consistent,
 user-friendly markdown summaries.
 """
 
-from basic_memory.schemas.memory import GraphContext
+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,
+)
 
-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.
+@dataclass
+class PromptContextItem:
+    primary_results: List[EntitySummary]
+    related_results: List[EntitySummary | RelationSummary | ObservationSummary]
 
-    Args:
-        header: The title to use for the summary
-        context: The GraphContext object to format
 
+@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 markdown string with the context summary
+        Formatted continuation 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}")` '
+    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]]
+                '''
             )
-            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}")` '
+            ```
+            
+            ## 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:
-                    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)
+                    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

@@ -8,4 +8,4 @@ configure_logging(level="INFO")
 
 
 # Create the shared server instance
-mcp = FastMCP("Basic Memory")
+mcp = FastMCP("Basic Memory")

basic_memory/mcp/tools/__init__.py

@@ -6,33 +6,22 @@ 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.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.canvas import canvas
 
-from basic_memory.mcp.tools.knowledge import (
-    delete_entities,
-    get_entity,
-    get_entities,
-)
-
 __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",
-    # files
-    "read_resource",
-    # canvas
-    "canvas",
 ]

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

@@ -6,7 +6,6 @@ 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
@@ -73,27 +72,26 @@ async def canvas(
     }
     ```
     """
-    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}"
+    # 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}
+    # Create canvas data structure
+    canvas_data = {"nodes": nodes, "edges": edges}
 
-        # Convert to JSON
-        canvas_json = json.dumps(canvas_data, indent=2)
+    # 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)
+    # 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)
+    # 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."]
+    # 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)
+    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())

basic_memory/mcp/tools/{resource.py → read_content.py}

@@ -1,3 +1,10 @@
+"""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
@@ -136,10 +143,40 @@ def optimize_image(img, content_length, max_output_bytes=350000):
             return buf.getvalue()
 
 
-@mcp.tool(description="Read a single file's content by path or permalink")
-async def read_resource(path: str) -> dict:
-    """Get a file's raw content."""
-    logger.info("Reading resource", path=path)
+@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}")
@@ -176,7 +213,7 @@ async def read_resource(path: str) -> dict:
     # Handle other file types
     else:
         logger.debug(f"Processing binary resource content_type {content_type}")
-        if content_length > 350000:
+        if content_length > 350000:  # pragma: no cover
             logger.warning("Document too large for response", size=content_length)
             return {
                 "type": "error",