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

basic_memory/cli/commands/tools.py

@@ -1,9 +1,10 @@
-"""Database management commands."""
+"""CLI tool commands for Basic Memory."""
 
 import asyncio
 from typing import Optional, List, Annotated
 
 import typer
+from loguru import logger
 from rich import print as rprint
 
 from basic_memory.cli.app import app
@@ -13,9 +14,15 @@ from basic_memory.mcp.tools import read_note as mcp_read_note
 from basic_memory.mcp.tools import recent_activity as mcp_recent_activity
 from basic_memory.mcp.tools import search as mcp_search
 from basic_memory.mcp.tools import write_note as mcp_write_note
+
+# Import prompts
+from basic_memory.mcp.prompts.continue_conversation import (
+    continue_conversation as mcp_continue_conversation,
+)
+
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import MemoryUrl
-from basic_memory.schemas.search import SearchQuery
+from basic_memory.schemas.search import SearchQuery, SearchItemType
 
 tool_app = typer.Typer()
 app.add_typer(tool_app, name="tools", help="cli versions mcp tools")
@@ -72,7 +79,7 @@ def build_context(
                 max_related=max_related,
             )
         )
-        rprint(context.model_dump())
+        rprint(context.model_dump_json(indent=2))
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
             typer.echo(f"Error during build_context: {e}", err=True)
@@ -82,18 +89,13 @@ def build_context(
 
 @tool_app.command()
 def recent_activity(
-    type: Annotated[Optional[List[str]], typer.Option()] = ["entity", "observation", "relation"],
+    type: Annotated[Optional[List[SearchItemType]], typer.Option()] = None,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
     page: int = 1,
     page_size: int = 10,
     max_related: int = 10,
 ):
-    assert type is not None, "type is required"
-    if any(t not in ["entity", "observation", "relation"] for t in type):  # pragma: no cover
-        print("type must be one of ['entity', 'observation', 'relation']")
-        raise typer.Abort()
-
     try:
         context = asyncio.run(
             mcp_recent_activity(
@@ -105,7 +107,7 @@ def recent_activity(
                 max_related=max_related,
             )
         )
-        rprint(context.model_dump())
+        rprint(context.model_dump_json(indent=2))
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
             typer.echo(f"Error during build_context: {e}", err=True)
@@ -132,14 +134,15 @@ def search(
     try:
         search_query = SearchQuery(
             permalink_match=query if permalink else None,
-            text=query if query else None,
+            text=query if not (permalink or title) else None,
             title=query if title else None,
             after_date=after_date,
         )
         results = asyncio.run(mcp_search(query=search_query, page=page, page_size=page_size))
-        rprint(results.model_dump())
+        rprint(results.model_dump_json(indent=2))
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
+            logger.exception("Error during search", e)
             typer.echo(f"Error during search: {e}", err=True)
             raise typer.Exit(1)
         raise
@@ -149,9 +152,29 @@ def search(
 def get_entity(identifier: str):
     try:
         entity = asyncio.run(mcp_get_entity(identifier=identifier))
-        rprint(entity.model_dump())
+        rprint(entity.model_dump_json(indent=2))
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
             typer.echo(f"Error during get_entity: {e}", err=True)
             raise typer.Exit(1)
         raise
+
+
+@tool_app.command(name="continue-conversation")
+def continue_conversation(
+    topic: Annotated[Optional[str], typer.Option(help="Topic or keyword to search for")] = None,
+    timeframe: Annotated[
+        Optional[str], typer.Option(help="How far back to look for activity")
+    ] = None,
+):
+    """Continue a previous conversation or work session."""
+    try:
+        # Prompt functions return formatted strings directly
+        session = asyncio.run(mcp_continue_conversation(topic=topic, timeframe=timeframe))
+        rprint(session)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            logger.exception("Error continuing conversation", e)
+            typer.echo(f"Error continuing conversation: {e}", err=True)
+            raise typer.Exit(1)
+        raise

basic_memory/cli/main.py

@@ -15,6 +15,5 @@ from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
     tools,
 )
 
-
 if __name__ == "__main__":  # pragma: no cover
     app()

basic_memory/config.py

@@ -3,9 +3,13 @@
 from pathlib import Path
 from typing import Literal
 
+from loguru import logger
 from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+import basic_memory
+from basic_memory.utils import setup_logging
+
 DATABASE_NAME = "memory.db"
 DATA_DIR_NAME = ".basic-memory"
 
@@ -31,7 +35,7 @@ class ProjectConfig(BaseSettings):
         default=500, description="Milliseconds to wait after changes before syncing", gt=0
     )
 
-    log_level: str = "INFO"
+    log_level: str = "DEBUG"
 
     model_config = SettingsConfigDict(
         env_prefix="BASIC_MEMORY_",
@@ -60,3 +64,13 @@ class ProjectConfig(BaseSettings):
 
 # Load project config
 config = ProjectConfig()
+
+# setup logging
+setup_logging(
+    env=config.env,
+    home_dir=config.home,
+    log_level=config.log_level,
+    log_file=".basic-memory/basic-memory.log",
+    console=False,
+)
+logger.info(f"Starting Basic Memory {basic_memory.__version__}")

basic_memory/file_utils.py

@@ -2,7 +2,7 @@
 
 import hashlib
 from pathlib import Path
-from typing import Dict, Any
+from typing import Dict, Any, Union
 
 import yaml
 from loguru import logger
@@ -26,12 +26,12 @@ class ParseError(FileError):
     pass
 
 
-async def compute_checksum(content: str) -> str:
+async def compute_checksum(content: Union[str, bytes]) -> str:
     """
     Compute SHA-256 checksum of content.
 
     Args:
-        content: Text content to hash
+        content: Content to hash (either text string or bytes)
 
     Returns:
         SHA-256 hex digest
@@ -40,7 +40,9 @@ async def compute_checksum(content: str) -> str:
         FileError: If checksum computation fails
     """
     try:
-        return hashlib.sha256(content.encode()).hexdigest()
+        if isinstance(content, str):
+            content = content.encode()
+        return hashlib.sha256(content).hexdigest()
     except Exception as e:  # pragma: no cover
         logger.error(f"Failed to compute checksum: {e}")
         raise FileError(f"Failed to compute checksum: {e}")

basic_memory/markdown/entity_parser.py

@@ -88,10 +88,10 @@ class EntityParser:
                 return parsed
         return None
 
-    async def parse_file(self, file_path: Path) -> EntityMarkdown:
+    async def parse_file(self, path: Path | str) -> EntityMarkdown:
         """Parse markdown file into EntityMarkdown."""
 
-        absolute_path = self.base_path / file_path
+        absolute_path = self.base_path / path
         # Parse frontmatter and content using python-frontmatter
         post = frontmatter.load(str(absolute_path))
 
@@ -99,7 +99,7 @@ class EntityParser:
         file_stats = absolute_path.stat()
 
         metadata = post.metadata
-        metadata["title"] = post.metadata.get("title", file_path.name)
+        metadata["title"] = post.metadata.get("title", absolute_path.name)
         metadata["type"] = post.metadata.get("type", "note")
         metadata["tags"] = parse_tags(post.metadata.get("tags", []))
 

basic_memory/mcp/async_client.py

@@ -2,7 +2,7 @@ from httpx import ASGITransport, AsyncClient
 
 from basic_memory.api.app import app as fastapi_app
 
-BASE_URL = "memory://"
+BASE_URL = "http://test"
 
 # Create shared async client
 client = AsyncClient(transport=ASGITransport(app=fastapi_app), base_url=BASE_URL)

basic_memory/mcp/main.py

@@ -0,0 +1,25 @@
+"""Main MCP entrypoint for Basic Memory.
+
+Creates and configures the shared MCP instance and handles server startup.
+"""
+
+from loguru import logger  # pragma: no cover
+
+from basic_memory.config import config  # pragma: no cover
+
+# Import shared mcp instance
+from basic_memory.mcp.server import mcp  # pragma: no cover
+
+# Import tools to register them
+import basic_memory.mcp.tools  # noqa: F401 # pragma: no cover
+
+# Import prompts to register them
+import basic_memory.mcp.prompts  # noqa: F401 # pragma: no cover
+
+
+
+if __name__ == "__main__":  # pragma: no cover
+    home_dir = config.home
+    logger.info("Starting Basic Memory MCP server")
+    logger.info(f"Home directory: {home_dir}")
+    mcp.run()

basic_memory/mcp/prompts/__init__.py

@@ -0,0 +1,15 @@
+"""Basic Memory MCP prompts.
+
+Prompts are a special type of tool that returns a string response
+formatted for a user to read, typically invoking one or more tools
+and transforming their results into user-friendly text.
+"""
+
+# Import individual prompt modules to register them with the MCP server
+from basic_memory.mcp.prompts import continue_conversation
+from basic_memory.mcp.prompts import recent_activity
+from basic_memory.mcp.prompts import search
+from basic_memory.mcp.prompts import ai_assistant_guide
+from basic_memory.mcp.prompts import json_canvas_spec
+
+__all__ = ["ai_assistant_guide", "continue_conversation", "json_canvas_spec", "recent_activity", "search"]

basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+import logfire
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+
+
+@mcp.resource(
+    uri="memory://ai_assistant_guide",
+    name="ai_assistant_guide",
+    description="Give an AI assistant guidance on how to use Basic Memory tools effectively",
+)
+def ai_assistant_guide() -> str:
+    """Return a concise guide on Basic Memory tools and how to use them.
+
+    Args:
+        focus: Optional area to focus on ("writing", "context", "search", etc.)
+
+    Returns:
+        A focused guide on Basic Memory usage.
+    """
+    with logfire.span("Getting Basic Memory guide"):  # pyright: ignore
+        logger.info("Loading AI assistant guide resource")
+        guide_doc = Path(__file__).parent.parent.parent.parent.parent / "data/ai_assistant_guide.md"
+        content = guide_doc.read_text()
+        logger.info(f"Loaded AI assistant guide ({len(content)} chars)")
+        return content

basic_memory/mcp/prompts/continue_conversation.py

@@ -0,0 +1,172 @@
+"""Session continuation prompts for Basic Memory MCP server.
+
+These prompts help users continue conversations and work across sessions,
+providing context from previous interactions to maintain continuity.
+"""
+
+from textwrap import dedent
+from typing import Optional, List, Annotated
+
+from loguru import logger
+import logfire
+from pydantic import Field
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.memory import build_context, recent_activity
+from basic_memory.mcp.tools.search import search
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import GraphContext
+from basic_memory.schemas.search import SearchQuery
+
+
+@mcp.prompt(
+    name="continue_conversation",
+    description="Continue a previous conversation",
+)
+async def continue_conversation(
+    topic: Annotated[Optional[str], Field(description="Topic or keyword to search for")] = None,
+    timeframe: Annotated[
+        Optional[TimeFrame],
+        Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
+    ] = None,
+) -> str:
+    """Continue a previous conversation or work session.
+
+    This prompt helps you pick up where you left off by finding recent context
+    about a specific topic or showing general recent activity.
+
+    Args:
+        topic: Topic or keyword to search for (optional)
+        timeframe: How far back to look for activity
+
+    Returns:
+        Context from previous sessions on this topic
+    """
+    with logfire.span("Continuing session", topic=topic, timeframe=timeframe):  # pyright: ignore
+        logger.info(f"Continuing session, topic: {topic}, timeframe: {timeframe}")
+
+        # If topic provided, search for it
+        if topic:
+            search_results = await search(SearchQuery(text=topic, after_date=timeframe))
+
+            # Build context from top results
+            contexts = []
+            for result in search_results.results[:3]:
+                if hasattr(result, "permalink") and result.permalink:
+                    context = await build_context(f"memory://{result.permalink}")
+                    contexts.append(context)
+
+            return format_continuation_context(topic, contexts, timeframe)
+
+        # If no topic, get recent activity
+        recent = await recent_activity(timeframe=timeframe)
+        return format_continuation_context("Recent Activity", [recent], timeframe)
+
+
+def format_continuation_context(
+    topic: str, contexts: List[GraphContext], timeframe: TimeFrame | None
+) -> str:
+    """Format continuation context into a helpful summary.
+
+    Args:
+        topic: The topic or focus of continuation
+        contexts: List of context graphs
+        timeframe: How far back to look for activity
+
+    Returns:
+        Formatted continuation summary
+    """
+    if not contexts or all(not context.primary_results for context in contexts):
+        return dedent(f"""
+            # Continuing conversation on: {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.
+            
+            I couldn't find any recent work specifically on this topic.
+            
+            ## Suggestions
+            - Try a different search term
+            - Check recent activity with `recent_activity(timeframe="1w")`
+            - Start a new topic with `write_note(...)`
+            """)
+
+    # Start building our summary with header
+    summary = dedent(f"""
+        # Continuing conversation on: {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 about the previous conversation:
+        """)
+
+    # Track what we've added to avoid duplicates
+    added_permalinks = set()
+    sections = []
+
+    # Process each context
+    for context in contexts:
+        # Add primary results
+        for primary in context.primary_results:
+            if hasattr(primary, "permalink") and primary.permalink not in added_permalinks:
+                added_permalinks.add(primary.permalink)
+
+                section = dedent(f"""
+                    ## {primary.title}
+                    - **Type**: {primary.type}
+                    """)
+
+                # Add creation date if available
+                if hasattr(primary, "created_at"):
+                    section += f"- **Created**: {primary.created_at.strftime('%Y-%m-%d %H:%M')}\n"
+
+                section += dedent(f"""
+                    
+                    You can read this document with: `read_note("{primary.permalink}")`
+                    """)
+
+                # Add related documents if available
+                related_by_type = {}
+                if context.related_results:
+                    for related in context.related_results:
+                        if hasattr(related, "relation_type") and related.relation_type:  # pyright: ignore
+                            if related.relation_type not in related_by_type:  # pyright: ignore
+                                related_by_type[related.relation_type] = []  # pyright: ignore
+                            related_by_type[related.relation_type].append(related)  # pyright: ignore
+
+                if related_by_type:
+                    section += dedent("""
+                        ### Related Documents
+                        """)
+                    for rel_type, relations in related_by_type.items():
+                        display_type = rel_type.replace("_", " ").title()
+                        section += f"- **{display_type}**:\n"
+                        for rel in relations[:3]:  # Limit to avoid overwhelming
+                            if hasattr(rel, "to_id") and rel.to_id:
+                                section += f"  - `{rel.to_id}`\n"
+
+                sections.append(section)
+
+    # Add all sections
+    summary += "\n".join(sections)
+
+    # Add next steps
+    next_steps = dedent(f"""
+        ## Next Steps
+        
+        You can:
+        - Explore more with: `search({{"text": "{topic}"}})`
+        - See what's changed: `recent_activity(timeframe="{timeframe}")`
+        """)
+
+    # Add specific exploration based on what we found
+    if added_permalinks:
+        first_permalink = next(iter(added_permalinks))
+        next_steps += dedent(f"""
+            - Continue the conversation: `build_context("memory://{first_permalink}")`
+            """)
+
+    return summary + next_steps

basic_memory/mcp/prompts/json_canvas_spec.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+
+import logfire
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+
+
+@mcp.resource(
+    uri="memory://json_canvas_spec",
+    name="json_canvas_spec",
+    description="JSON Canvas specification for visualizing knowledge graphs in Obsidian"
+)
+def json_canvas_spec() -> str:
+    """Return the JSON Canvas specification for Obsidian visualizations.
+    
+    Returns:
+        The JSON Canvas specification document.
+    """
+    with logfire.span("Getting JSON Canvas spec"):  # pyright: ignore
+        logger.info("Loading JSON Canvas spec resource")
+        canvas_spec = Path(__file__).parent.parent.parent.parent.parent / "data/json_canvas_spec_1_0.md"
+        content = canvas_spec.read_text()
+        logger.info(f"Loaded JSON Canvas spec ({len(content)} chars)")
+        return content

basic_memory/mcp/prompts/recent_activity.py

@@ -0,0 +1,46 @@
+"""Recent activity prompts for Basic Memory MCP server.
+
+These prompts help users see what has changed in their knowledge base recently.
+"""
+
+from typing import Annotated, Optional
+
+from loguru import logger
+import logfire
+from pydantic import Field
+
+from basic_memory.mcp.prompts.utils import format_context_summary
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.memory import recent_activity as recent_activity_tool
+from basic_memory.schemas.base import TimeFrame
+
+
+@mcp.prompt(
+    name="recent_activity",
+    description="Get recent activity from across the knowledge base",
+)
+async def recent_activity_prompt(
+    timeframe: Annotated[
+        Optional[TimeFrame],
+        Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
+    ] = None,
+) -> str:
+    """Get recent activity from across the knowledge base.
+
+    This prompt helps you see what's changed recently in the knowledge base,
+    showing new or updated documents and related information.
+
+    Args:
+        timeframe: How far back to look for activity (e.g. '1d', '1 week')
+
+    Returns:
+        Formatted summary of recent activity
+    """
+    with logfire.span("Getting recent activity", timeframe=timeframe):  # pyright: ignore
+        logger.info(f"Getting recent activity, timeframe: {timeframe}")
+
+        results = await recent_activity_tool(timeframe=timeframe)
+
+        time_display = f" ({timeframe})" if timeframe else ""
+        header = f"# Recent Activity{time_display}"
+        return format_context_summary(header, results)

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