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

basic_memory/file_utils.py

@@ -2,11 +2,13 @@
 
 import hashlib
 from pathlib import Path
-from typing import Dict, Any, Union
+from typing import Any, Dict, Union
 
 import yaml
 from loguru import logger
 
+from basic_memory.utils import FilePath
+
 
 class FileError(Exception):
     """Base exception for file operations."""
@@ -48,42 +50,47 @@ async def compute_checksum(content: Union[str, bytes]) -> str:
         raise FileError(f"Failed to compute checksum: {e}")
 
 
-async def ensure_directory(path: Path) -> None:
+async def ensure_directory(path: FilePath) -> None:
     """
     Ensure directory exists, creating if necessary.
 
     Args:
-        path: Directory path to ensure
+        path: Directory path to ensure (Path or string)
 
     Raises:
         FileWriteError: If directory creation fails
     """
     try:
-        path.mkdir(parents=True, exist_ok=True)
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+        path_obj.mkdir(parents=True, exist_ok=True)
     except Exception as e:  # pragma: no cover
-        logger.error(f"Failed to create directory: {path}: {e}")
+        logger.error("Failed to create directory", path=str(path), error=str(e))
         raise FileWriteError(f"Failed to create directory {path}: {e}")
 
 
-async def write_file_atomic(path: Path, content: str) -> None:
+async def write_file_atomic(path: FilePath, content: str) -> None:
     """
     Write file with atomic operation using temporary file.
 
     Args:
-        path: Target file path
+        path: Target file path (Path or string)
         content: Content to write
 
     Raises:
         FileWriteError: If write operation fails
     """
-    temp_path = path.with_suffix(".tmp")
+    # Convert string to Path if needed
+    path_obj = Path(path) if isinstance(path, str) else path
+    temp_path = path_obj.with_suffix(".tmp")
+
     try:
         temp_path.write_text(content)
-        temp_path.replace(path)
-        logger.debug(f"wrote file: {path}")
+        temp_path.replace(path_obj)
+        logger.debug("Wrote file atomically", path=str(path_obj), content_length=len(content))
     except Exception as e:  # pragma: no cover
         temp_path.unlink(missing_ok=True)
-        logger.error(f"Failed to write file: {path}: {e}")
+        logger.error("Failed to write file", path=str(path_obj), error=str(e))
         raise FileWriteError(f"Failed to write file {path}: {e}")
 
 
@@ -173,7 +180,7 @@ def remove_frontmatter(content: str) -> str:
     return parts[2].strip()
 
 
-async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
+async def update_frontmatter(path: FilePath, updates: Dict[str, Any]) -> str:
     """Update frontmatter fields in a file while preserving all content.
 
     Only modifies the frontmatter section, leaving all content untouched.
@@ -181,7 +188,7 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
     Returns checksum of updated file.
 
     Args:
-        path: Path to markdown file
+        path: Path to markdown file (Path or string)
         updates: Dict of frontmatter fields to update
 
     Returns:
@@ -192,8 +199,11 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
         ParseError: If frontmatter parsing fails
     """
     try:
+        # Convert string to Path if needed
+        path_obj = Path(path) if isinstance(path, str) else path
+
         # Read current content
-        content = path.read_text()
+        content = path_obj.read_text()
 
         # Parse current frontmatter
         current_fm = {}
@@ -208,9 +218,15 @@ async def update_frontmatter(path: Path, updates: Dict[str, Any]) -> str:
         yaml_fm = yaml.dump(new_fm, sort_keys=False)
         final_content = f"---\n{yaml_fm}---\n\n{content.strip()}"
 
-        await write_file_atomic(path, final_content)
+        logger.debug("Updating frontmatter", path=str(path_obj), update_keys=list(updates.keys()))
+
+        await write_file_atomic(path_obj, final_content)
         return await compute_checksum(final_content)
 
     except Exception as e:  # pragma: no cover
-        logger.error(f"Failed to update frontmatter in {path}: {e}")
+        logger.error(
+            "Failed to update frontmatter",
+            path=str(path) if isinstance(path, (str, Path)) else "<unknown>",
+            error=str(e),
+        )
         raise FileError(f"Failed to update frontmatter: {e}")

basic_memory/markdown/utils.py

@@ -5,6 +5,7 @@ from typing import Optional, Any
 
 from frontmatter import Post
 
+from basic_memory.file_utils import has_frontmatter, remove_frontmatter
 from basic_memory.markdown import EntityMarkdown
 from basic_memory.models import Entity, Observation as ObservationModel
 from basic_memory.utils import generate_permalink
@@ -78,6 +79,10 @@ async def schema_to_markdown(schema: Any) -> Post:
     content = schema.content or ""
     frontmatter_metadata = dict(schema.entity_metadata or {})
 
+    # if the content contains frontmatter, remove it and merge
+    if has_frontmatter(content):
+        content = remove_frontmatter(content)
+
     # Remove special fields for ordered frontmatter
     for field in ["type", "title", "permalink"]:
         frontmatter_metadata.pop(field, None)

basic_memory/mcp/main.py

@@ -17,9 +17,8 @@ import basic_memory.mcp.tools  # noqa: F401 # pragma: no cover
 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()
+    mcp.run()

basic_memory/mcp/prompts/__init__.py

@@ -10,6 +10,10 @@ 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"]
+__all__ = [
+    "ai_assistant_guide",
+    "continue_conversation",
+    "recent_activity",
+    "search",
+]

basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -1,6 +1,5 @@
 from pathlib import Path
 
-import logfire
 from loguru import logger
 
 from basic_memory.mcp.server import mcp
@@ -8,7 +7,7 @@ from basic_memory.mcp.server import mcp
 
 @mcp.resource(
     uri="memory://ai_assistant_guide",
-    name="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:
@@ -20,9 +19,8 @@ def ai_assistant_guide() -> str:
     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
+    logger.info("Loading AI assistant guide resource")
+    guide_doc = Path(__file__).parent.parent.parent.parent.parent / "static" / "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

@@ -5,22 +5,23 @@ providing context from previous interactions to maintain continuity.
 """
 
 from textwrap import dedent
-from typing import Optional, List, Annotated
+from typing import Optional, Annotated
 
 from loguru import logger
-import logfire
 from pydantic import Field
 
+from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext, PromptContextItem
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.memory import build_context, recent_activity
+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.search import search
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import GraphContext
-from basic_memory.schemas.search import SearchQuery
+from basic_memory.schemas.search import SearchQuery, SearchItemType
 
 
 @mcp.prompt(
-    name="continue_conversation",
+    name="Continue Conversation",
     description="Continue a previous conversation",
 )
 async def continue_conversation(
@@ -42,131 +43,69 @@ async def continue_conversation(
     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)
-
+    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, types=[SearchItemType.ENTITY])
+        )
+
+        # Build context from results
+        contexts = []
+        for result in search_results.results:
+            if hasattr(result, "permalink") and result.permalink:
+                context: GraphContext = await build_context(f"memory://{result.permalink}")
+                if context.primary_results:
+                    contexts.append(
+                        PromptContextItem(
+                            primary_results=context.primary_results[:1],  # pyright: ignore
+                            related_results=context.related_results[:3],  # pyright: ignore
+                        )
+                    )
+
+        # get context for the top 3 results
+        prompt_context = format_prompt_context(
+            PromptContext(topic=topic, timeframe=timeframe, results=contexts)  # pyright: ignore
+        )
+
+    else:
         # 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
+        timeframe = timeframe or "7d"
+        recent: GraphContext = await recent_activity(
+            timeframe=timeframe, type=[SearchItemType.ENTITY]
+        )
+        prompt_context = format_prompt_context(
+            PromptContext(
+                topic=f"Recent Activity from ({timeframe})",
+                timeframe=timeframe,
+                results=[
+                    PromptContextItem(
+                        primary_results=recent.primary_results[:5],  # pyright: ignore
+                        related_results=recent.related_results[:2],  # pyright: ignore
+                    )
+                ],
+            )
+        )
+
+    # Add next steps with strong encouragement to write
     next_steps = dedent(f"""
         ## Next Steps
-        
+
         You can:
         - Explore more with: `search({{"text": "{topic}"}})`
-        - See what's changed: `recent_activity(timeframe="{timeframe}")`
+        - See what's changed: `recent_activity(timeframe="{timeframe or "7d"}")`
+        - **Record new learnings or decisions from this conversation:** `write_note(title="[Create a meaningful title]", content="[Content with observations and relations]")`
+        
+        ## Knowledge Capture Recommendation
+        
+        As you continue this conversation, **actively look for opportunities to:**
+        1. Record key information, decisions, or insights that emerge
+        2. Link new knowledge to existing topics 
+        3. Suggest capturing important context when appropriate
+        4. Create forward references to topics that might be created later
+        
+        Remember that capturing knowledge during conversations is one of the most valuable aspects of Basic Memory.
         """)
 
-    # 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
+    return prompt_context + next_steps

basic_memory/mcp/prompts/recent_activity.py

@@ -3,27 +3,27 @@
 These prompts help users see what has changed in their knowledge base recently.
 """
 
-from typing import Annotated, Optional
+from typing import Annotated
 
 from loguru import logger
-import logfire
 from pydantic import Field
 
-from basic_memory.mcp.prompts.utils import format_context_summary
+from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext, PromptContextItem
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.memory import recent_activity as recent_activity_tool
+from basic_memory.mcp.tools.recent_activity import recent_activity
 from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.prompt(
-    name="recent_activity",
+    name="Share Recent Activity",
     description="Get recent activity from across the knowledge base",
 )
 async def recent_activity_prompt(
     timeframe: Annotated[
-        Optional[TimeFrame],
+        TimeFrame,
         Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
-    ] = None,
+    ] = "7d",
 ) -> str:
     """Get recent activity from across the knowledge base.
 
@@ -36,11 +36,53 @@ async def recent_activity_prompt(
     Returns:
         Formatted summary of recent activity
     """
-    with logfire.span("Getting recent activity", timeframe=timeframe):  # pyright: ignore
-        logger.info(f"Getting recent activity, timeframe: {timeframe}")
+    logger.info(f"Getting recent activity, timeframe: {timeframe}")
 
-        results = await recent_activity_tool(timeframe=timeframe)
+    recent = await recent_activity(timeframe=timeframe, type=[SearchItemType.ENTITY])
 
-        time_display = f" ({timeframe})" if timeframe else ""
-        header = f"# Recent Activity{time_display}"
-        return format_context_summary(header, results)
+    prompt_context = format_prompt_context(
+        PromptContext(
+            topic=f"Recent Activity from ({timeframe})",
+            timeframe=timeframe,
+            results=[
+                PromptContextItem(
+                    primary_results=recent.primary_results[:5],
+                    related_results=recent.related_results[:2],
+                )
+            ],
+        )
+    )
+
+    # Add suggestions for summarizing recent activity
+    capture_suggestions = f"""
+    ## Opportunity to Capture Activity Summary
+    
+    Consider creating a summary note of recent activity:
+    
+    ```python
+    await write_note(
+        title="Activity Summary {timeframe}",
+        content='''
+        # Activity Summary for {timeframe}
+        
+        ## Overview
+        [Summary of key changes and developments over this period]
+        
+        ## Key Updates
+        [List main updates and their significance]
+        
+        ## Observations
+        - [trend] [Observation about patterns in recent activity]
+        - [insight] [Connection between different activities]
+        
+        ## Relations
+        - summarizes [[{recent.primary_results[0].title if recent.primary_results else "Recent Topic"}]]
+        - relates_to [[Project Overview]]
+        '''
+    )
+    ```
+    
+    Summarizing periodic activity helps create high-level insights and connections between topics.
+    """
+
+    return prompt_context + capture_suggestions

basic_memory/mcp/prompts/search.py

@@ -7,17 +7,16 @@ 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
+from basic_memory.schemas.search import SearchQuery, SearchResponse
 
 
 @mcp.prompt(
-    name="search",
+    name="Search Knowledge Base",
     description="Search across all content in basic-memory",
 )
 async def search_prompt(
@@ -39,11 +38,10 @@ async def search_prompt(
     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}")
+    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)
+    search_results = await search_tool(SearchQuery(text=query, after_date=timeframe))
+    return format_search_results(query, search_results, timeframe)
 
 
 def format_search_results(
@@ -65,11 +63,33 @@ def format_search_results(
             
             I couldn't find any results for this query.
             
-            ## Suggestions
+            ## 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")`
-            - Create new content with `write_note(...)`
             """)
 
     # Start building our summary with header
@@ -88,32 +108,38 @@ def format_search_results(
     for i, result in enumerate(results.results[:5]):  # Limit to top 5 results
         summary += dedent(f"""
             ## {i + 1}. {result.title}
-            - **Type**: {result.type}
+            - **Type**: {result.type.value}
             """)
 
         # Add creation date if available in metadata
-        if hasattr(result, "metadata") and result.metadata and "created_at" in result.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"
+                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 hasattr(result, "metadata") and result.metadata and "excerpt" in result.metadata:
-            summary += f"- **Excerpt**: {result.metadata['excerpt']}\n"
+        if result.content:
+            summary += f"- **Excerpt**:\n{result.content}\n"
 
         # Add permalink for retrieving content
-        if hasattr(result, "permalink") and result.permalink:
+        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
+    # Add next steps with strong write encouragement
     summary += dedent(f"""
         ## Next Steps
         
@@ -122,6 +148,35 @@ def format_search_results(
         - 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